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
