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 <schwa...@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
