On Thu, Aug 21, 2025 at 08:33:01AM -0500, Clinton Bunch wrote: > > * You don't need you system to support html and pdf: roff does it for > > you (also postscript) > roff produces horrible HTML with no styling capability. It's a typesetter > not a documentation format. that's why mandoc add semantic to it. It is meant for printed pages. nope! troff if but nroff is for the terminal! I'm currious to see how sphinx goes when it comes to produce a content to be shown with less -R. > > * don't you think the natural format for a unix shell should be the unix > > typesetting system? > No. Because typesetting is about presentation, not documentation. mandoc is about documentation, roff is the native format of man pages. wrappers are useful when target langages are painful (obviously html, xml and things like that) > > * will we loose semantic using RST? > RST has much richer semantics than roff. roff has no semantic: it has rendering primitives and you write your own semantic on it. again: please read the mandoc documentation. > > * the troff syntax is simple, yet powerful enough and extendable > > * the mandoc requests add semantic to everything we need (flags, > > subcommands, parameters, ...) which appears in output formats > > (give a look at https://man.openbsd.org/) > We need a lot more than flags, subcommands, and parameters. Yes. I know the yodl doc and and I would have be quiet if mandoc where not good enough. > > > Sphinx will generate man, html, pdf, and texi formats from rst > > which is complete redundant with man format. > Not all documentation is a man page. do you have an example in the zsh doc that could be something else? > I've been reading man pages for more than three decades, they lack internal > cross referencing and indexes, it's hard to find the specific information > you need quickly. Especially in a large man page like a shell. yes ... the man request package is quiet old and that's why mandoc was meant for! please provide me some part of the documentation that makes you feel insecure so we can think and share from concrete exemples. also mandoc is everywhere now. regards -- Marc Chantreux Pôle CESAR (Calcul et services avancés à la recherche) Université de Strasbourg 14 rue René Descartes, BP 80010, 67084 STRASBOURG CEDEX 03.68.85.60.79
Attachment:
signature.asc
Description: PGP signature