News for hackers. Stuff that matters.
Re:Practical Unix Manuals: mdoc by emj on Saturday November 25, 2017 @09:49AM (#15776153)
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.
Re:Practical Unix Manuals: mdoc by beefhash on Saturday November 25, 2017 @10:00AM (#15776196)
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

Re:Practical Unix Manuals: mdoc by nerdponx on Saturday November 25, 2017 @10:40AM (#15776353)
I wish I could use semantic markup to jump to a definition, either of an option or a subcommand.
Re:Practical Unix Manuals: mdoc by yepguy on Saturday November 25, 2017 @03:16PM (#15777753)
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.
Re:Practical Unix Manuals: mdoc by nerdponx on Sunday November 26, 2017 @10:37AM (#15781313)
Interesting, so theoretically that is something that every distro could and should be doing?
Re:Practical Unix Manuals: mdoc by humanrebar on Saturday November 25, 2017 @10:09AM (#15776225)
When does someone need to search for that sort of thing?
Re:Practical Unix Manuals: mdoc by beefhash on Saturday November 25, 2017 @10:12AM (#15776238)
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...

Re:Practical Unix Manuals: mdoc by jwilk on Saturday November 25, 2017 @11:57AM (#15776697)
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.
Re:Practical Unix Manuals: mdoc by clort on Sunday November 26, 2017 @01:36PM (#15782273)
> 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.

Re:Practical Unix Manuals: mdoc by emj on Tuesday November 28, 2017 @08:40PM (#15803731)
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.
Re:Practical Unix Manuals: mdoc by nerdponx on Saturday November 25, 2017 @10:17AM (#15776261)
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.
Re:Practical Unix Manuals: mdoc by emj on Tuesday November 28, 2017 @08:43PM (#15803744)
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.
Re:Practical Unix Manuals: mdoc by DC-3 on Sunday November 26, 2017 @07:00AM (#15780534)
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.
Re:Practical Unix Manuals: mdoc by nerdponx on Sunday November 26, 2017 @10:38AM (#15781316)
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.
Re:Practical Unix Manuals: mdoc by goialoq on Saturday November 25, 2017 @11:27AM (#15776586)
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.