Re: Modernising UNIX manpages.

[JM Marcastel]

> On 22 Apr 2021, at 18:37, JM Marcastel <don@marcastel.com> wrote:
> 
>> On 22 Apr 2021, at 09:35, Marc Chantreux <eiro@phear.org 
>> <mailto:eiro@phear.org>> wrote:
>> 
>> There is no way you'll manage requests like .In, .Fn .Vt, .Ft, .Fn, .Op
>> with commonmark.
> 
> 
> Food for thought… though in my opinion the usage strings and the synopsis are 
> like a table of contents, automatically generated.

FWIW playing around with the bare bones template in `groff_mdoc(7)` here are a 
few files to illustrate my thoughts.

skeleton.yaml — a first attempt a what the format could look like
skeleton.{hcl,json,kaml,toml, ast} — outputs as generated by a tool of mine

Here is a glimpse at the first file:

--- # The follow structured is required for all man pages
revision  : 2021-04-22 (Thu) 19:22:58
name      : <name>
brief     : <one-line-description>
title     : <document-title>
volume    : <architecture/volume>
system    : <operating-system>
release   : <release/version> <release-date>
status    : draft
sections  :
  - name  : NAME            # This section is automatically generated
                            # if you do not fill it in

  - name  : LIBRARY         # For MAN sections 2 and 3 only

  - name  : SYNOPSIS        # This section is automatically generated
                            # for command line interfaces

  - name  : DESCRIPTION     #   
    body  : |

            A **man page** (short for **manual page**) is a form of [software
            documentation] usually found on a [UNIX] or [UNIX-like] [operating
            system][os].

            ![A diagram showing the key Unix and Unix-like operating 
systems][UNIX-chart]

            and a (simple) table for Eric :-)

            | Option | Description |
            | ------ | ----------- |
            | data   | path to data files to supply the data that will be 
passed into templates. |
            | engine | engine to be used for processing templates. Handlebars 
is the default. |
            | ext    | extension to be used for dest files. |


              [software documentation]: 
https://en.wikipedia.org/wiki/Software_documentation
              [UNIX]: https://en.wikipedia.org/wiki/Unix
              [UNIX-like]: https://en.wikipedia.org/wiki/Unix-like
              [os]: https://en.wikipedia.org/wiki/Operating_system
              [UNIX-chart]: 
https://en.wikipedia.org/wiki/Unix#/media/File:Unix_history-simple.svg

  - name  : DESCRIPTION     # Use free form (Pandoc) Markdown
  - name  : IMPLEMENTATION NOTES    # Where necessary
  - name  : RETURN VALUES           # For sections 2, 3 and 9 functions
  - name  : ENVIRONMENT             # For sections 1, 6, 7 and 8 only.
  - name  : FILES
  - name  : EXAMPLES
  - name  : DIAGNOSTICS             # For sections 1, 6, 7, 8 and 9 only
  - name  : COMPATIBILITY
  - name  : ERRORS                  # For sections 2, 3 and 9
  - name  : SEE ALSO
  - name  : STANDARDS
  - name  : HISTORY
  - name  : AUTHORS
  - name  : BUGS

---


The `skeleton.ast` is an abstract syntax tree modelled after the one Pandoc 
provides (and could be aligned to the C implementation of CommonMark).

Producing the AST with pandoc is simply a matter of : `pandoc -i skeleton.yaml 
-o skeleton.ast -f markdown -t json`

My utility is a very simple wrapper around `libyaml` which enables direct 
manipulation of YAML/JSON/TOML in KornShell scripts by converting them to (KAML 
<https://github.com/ISLEcode/KAML> <https://github.com/ISLEcode/KAML 
<https://github.com/ISLEcode/KAML>>).

Generating, from a KornShell script, outputs in nroff, HTML, PDF (or any of 
Pandoc’s 59 supported output formats — see pandoc —list-output-formats) is 
simply a matter of:

print -v body | pandoc —template manpage.<ext> —to <format>




y2k -- convert a YAML stream or file into a KAML equivalent.
Usage: y2k [-a] [-c] [-d] [-f] [-k] [-m] [-p <name>] [-u] [-v] <file>

  -a         output mappings as associative arrays
  -c         output in the canonical YAML format
  -k         output KornShell rather than KAML
  -d         enable the debug mode
  -f         only parse frontmatter YAML in Markdown documents
  -m         minify output (disables verbosity) [experimental]
  -p <name>  assign output to variable <name>, appropriately prefixed
             with a `typeset` (implies -k)
  -u         output unescaped non-ASCII characters
  -v         increase the verbosity level (max: 3)

For illustration, I attach a couple of screenshots of terminal rendered 
Markdown using glow (the file is Pandoc’s manpage 
<https://github.com/jgm/pandoc/blob/master/MANUAL.txt> (in Markdown which is 
automatically converted to nroff))

Note: Glow’s markdown syntax is currently too limited for our purposes. The 
output is currently crippled in places. But the utility’s design (Charm 
library) allows easy expansion and could be plugged directly to the AST.