4 ms·
I love man pages they are often easy to read, but roff is not that easy to author. So it nice to see good documentation being posted. .Sh SYNOPSIS .Nm
by emj 9y ago
I love man pages they are often easy to read, but roff is not that easy to author. So it nice to see good documentation being posted.
.Sh SYNOPSIS
.Nm
.Op Fl C
.Op Fl o Ar output
.Op Ar prefix
becomes this:
SYNOPSIS
hello [-C] [-o output] [prefix]
Semantic formating is nice, but atm I'm not sure there is much value to write the above vs using markdown and just convert it to roff.
- beefhash 9y agoSemantic markup has a use, at least on OpenBSD. You can use the semantic markup for searching manual pages, like this[1]: > Search for manuals in the library section mentioning both the “optind” and the “optarg” variables: > $ apropos -s 3 Va=optind -a Va=optarg [1] https://man.openbsd.org/whatis.1 https://man.openbsd.org/whatis.1
- humanrebar 9y agoWhen does someone need to search for that sort of thing?
- beefhash 9y agoA more realistic example might be that you're changing $LANG and now something broke. You can thus search for everything that uses LANG[1] and see what's most likely to have broken in what way. [1] https://man.openbsd.org/?query=Ev%3DLANG&apropos=1&sec=0&arch=default&manpath=OpenBSD-current https://man.openbsd.org/?query=Ev%3DLANG&apropos=1&sec=0&arc...
- jwilk 9y agoThere are some many things that are affected by locale environment variables (most of the time without documenting it explicitly), that this particular query is mostly useless.
- nerdponx 9y agoI wish I could use semantic markup to jump to a definition, either of an option or a subcommand.
- yepguy 9y agoYou can actually. If you use mandoc instead of mandb, it automatically generates and passes tag files to less. Then you can just type ":t e" to jump to the docs for the -e option, for example.
- nerdponx 9y agoInteresting, so theoretically that is something that every distro could and should be doing?
- nerdponx 9y agoI'm not sure Markdown->Roff makes sense. I know Pandoc can do it, but how do you convey semantic information with Markdown? I'd sooner write YAML.
- DC-3 9y agoIt might not be trendy like Markdown or YAML (both of which I like, and have their uses), but to markup text with higher-level semantics (i.e. not relating to formatting) the best option is XML.
- nerdponx 9y agoSure, but do you really want to hand write XML? It's nice for computers but makes for really ugly source when humans are involved, and humans are still very heavily involved when it comes to writing documentation.
- emj 9y agoIt works, not as good as a good template for LibreOffice though, my point was that the sematics is lost with markdown and you only get formating.
- goialoq 9y agoMost of the problem with that is the cryptic abbreviations. A symbol lexical filter would let you have this: .SectionHeader .Name .Optional Flag C .Optional Flag o Argument output .Optional Argument prefix or with some punctuation: .SectionHeader .Name .Optional Flag: C .Optional Flag: o Argument: output .Optional Argument: prefix which is quite readable.
- clort 9y ago> I love man pages they are often easy to read, but roff is not that easy to author To be fair, writing the programs or functions that the manual page is purporting to document isn't easy either. I have written manpages (and plenty of code) and in my experience, the hardest part is not the markup but getting the actual content right.
- emj 9y agoThere are badly written documentation out there, and they will not be better just because they are formated as a man page instead of Microsoft Word, but the worst kind are the ones which are never written and that syntax is quite a blocker. Your comment highlights my bias for man pages, I forgive a lot more when it's read in prefered format rather than .docs.