Hello,
A very good explanation. All crystal clear now, i thank you for your time.
I had a strange idea in the late night about replacing something with
something else, but i see it is not the case and there is no need to
elaborate.
Thank you.
On Thu, Dec 28, 2023 at 3:46 AM Ingo Schwarze <schwarze@usta.de> wrote:
>
> Hi Mihai,
>
> Mihai Popescu wrote on Thu, Dec 28, 2023 at 01:32:34AM +0200:
>
> > [ removed elaborate instruction about going html from almost txt with
> > man pages ]
> >
> > All this to jump in html boat? Or I got it wrong?
> > Are old man pages deprecated?
>
> Manual pages are not restricted to a specific output format.
>
> THE traditional output format, as far as such a thing exists, is
> black markings on dead trees. That output format later evolved into
> PostScript format and still later into PDF format. Let's call all
> these output modes "typeset output".
>
> Another very old output format is video terminal (CRT) output.
> That's still used a lot, though mostly via virtual terminals nowadays
> rather than on CRTs. But all that is clearly younger than typeset
> output mode.
>
> It has already been explained why nowdays (meaning: during the
> last three decades) it has become convenient to also be able to
> access information remotely via the WWW. The simplest format to
> facilitate that has always been HTML.
>
> Even more recently (as in: during the last decade) source code
> management platforms have become popular that require documentation
> in Markdown format. So that's just another output mode for manual
> pages, see for example
>
> https://github.com/Tairokiya/rfind
> (even though using manual page format isn't widespread on that
> particular platform yet, and this example is of poor quality
> in several respects)
>
> or
>
> https://codeberg.org/fobser/gelatod
> (even though the software used by Codeberg, Forgejo, is currently
> haunted by a bug that prevents correct rendering of the
> standard-conforming Markdown (specifically, CommonMark) code
> generated from manual pages, as you can see - but that bug is
> already fixed and will be gone from the next Forgejo release)
>
>
> So, if the output format is *not* what defines manual pages, then is it
> that defines them?
>
> 1. The idea of having one self-contained document ("manual page")
> for each interface (specifically, CLI command in sections 1 and 8,
> system call in section 2, API function in section 3, kernel driver
> in section 4, configuration file in section 5, domain specific
> language in section 7, kernel function in section 9)
>
> 2. Each of these documents being complete but concise, i.e. not
> mixing in explanations of required prior knowledge about the
> foundations the interface is built on, nor containing tutorial-
> style instructions
>
> 3. A common structure consisting of
> - a one-line description (name section)
> - an informal (i.e. non-BNF), human readable syntax display
> (synopsis section)
> - a description of the arguments and behaviour (description section)
> - various standardized auxiliary sections like "return values",
> "environment", "files", "exit status", "errors", "see also",
> "standards" and so on, to help quickly locate information
> that often needs to be looked up
>
> 4. Universal tygographic conventions helping readability of the
> page for anyone familiar with other manual pages, no matter
> who wrote the particular page currently being looked at
>
> Using HTML output format for reading manual pages allows taking full
> advantage of these concepts just like any other output format does.
> So there is really no need to bash HTML as a manual page output
> format. Also remeber that HTML output format may be particularly
> convenient for people having specific accessibility requirements,
> for example blind people.
>
>
> Maybe what you had in mind is that some software authors abuse HTML as
> an *input* format for documentation, that they write documentation for
> their software directly in HTML format (instead of writing manual pages,
> which can then trivially be convented to HTML if desired, and additionally
> to many other formats). *Maintaining* documentation in HTML format is
> indeed a very bad idea. That usually results in documentation that is
> disorganized, sprawling rather than concise, hinders locating information,
> is riddled with idiosyncratic formatting choices, and next to impossible
> to convert to any other format.
>
> Yours,
> Ingo
No comments:
Post a Comment