in reply to Re: Reading Perl documentation in Emacs
in thread Reading Perl documentation in Emacs

Agreed, man pages (nroff pages) can be built on-the-fly in the same way as I'm doing it with HTML right now. But then - it's still nroff. If I have to choose between nroff and HTML, then I'd say HTML is the way to go for structured documentation.

  • Comment on Re^2: Reading Perl documentation in Emacs

Replies are listed 'Best First'.
Re^3: Reading Perl documentation in Emacs
by LanX (Saint) on Mar 13, 2023 at 14:43 UTC
    > then I'd say HTML is the way to go for structured documentation.

    Could you please elaborate?

    woman seems to render much faster than html.

    POD was primarily designed for man, and the L<...> link format has it's ambiguities AFAIR.

    I'd say HTML is the way to go if you supported more advanced features, like external links, embedded pics or special formatters in =for ... drectives. But those are sparsely used.

    Of course if you decided to support an external document server like Pod::POM::Web , man wouldn't be an option.

    Any other points I missed?

    Cheers Rolf
    (addicted to the 𐍀𐌴𐍂𐌻 Programming Language :)
    Wikisyntax for the Monastery

[reply]
[d/l]
[select]

      > then I'd say HTML is the way to go for structured documentation.

      Could you please elaborate?

      Sure. HTML is powerful enough to express all POD markup. I consider linking to other documents very useful in technical documentation.
      woman seems to render much faster than html.
      Rendering speed is very low on my priority list.
      POD was primarily designed for man, ...
      Irrelevant. POD pre-dates HTML. In the 1990s I worked with a 25 lines / 80 (or 132) columns terminal. Back then it wasn't unusual to actually print man pages. Today I read technical documentation almost exclusively online. My requirements are now based on online reading, where man doesn't shine.
      ... and the L<...>link format has it's ambiguities AFAIR.
      Your turn to elaborate: What message are you trying to send? perlpodspec has a lot to say on the topic About L<...> Codes. I stick to the current spec, which includes a recommendation for heuristics how to deal with old, ambiguous links. perl-doc doesn't catch all links, but it works often enough to be above the threshold of goodenoughness.
      I'd say HTML is the way to go if you supported more advanced features...
      Indeed. POD enhancements which have already been discussed on P5P (no RFC/PPC yet) are tables and images. Both are supported by HTML and by the libraries used by perl-doc.

      All that said: Emacs 29 comes with tree-sitter libraries, and I hope that the mainstream distributions will include these in their builds. The real competition for all HTML/man/info intermediates will then be native POD support in Emacs, based on tree-sitter-pod.

[reply]

In Section Meditations