Hacker News Reader

Comment by emj | Hacker News Reader

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.

View on HN

Semantic 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

When does someone need to search for that sort of thing?

A 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&arc...

There 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.

I wish I could use semantic markup to jump to a definition, either of an option or a subcommand.

You 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.

Interesting, so theoretically that is something that every distro could and should be doing?

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

There 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.

I'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.

It 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.

Sure, 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.

It 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.

Most 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.

Reply on news.ycombinator.com