CODEWITHSUNDEEP
formattingmarkdownpandocmanpage
user32849
user32849

Reputation: 649

Nested lists in man page using Pandoc

I am trying to create the following manpage, by specifying a MarkDown file and using PanDoc to convert it to different formats (just a nonsensical example for demonstration, the actual version makes sense, but is much longer):

-i, --input-type
    Specify the input type. Choices include
    1. float
        * signed
        * unsigned
    2. integer
    3. bool
    Other data types will cause an exception. You should therefore
    be very careful what you put in here.

-o, --output
    The name of the output file.

I am using 

pandoc myapp.md -s -t man > myapp.man

Pandoc uses the following conventions for markdown intended for this type of manpage conversion:

**-f** *FILE*, **--input-file**  *FILE*
:   Read input data from *FILE*.

**-o** *FILE*
: Output file.

I've played around with various list definitions, indentations and line breaks (two spaces at line end), but I cannot seem to get this to work in all output (PDF, HTML, man). I either get * interpreted literally, or the indentation is missing, or the last line of the -i option is wrapped so that its second visual line is missing indentations. Any idea how to achieve the above?

Upvotes: 1

Views: 1587

Answers (2)

user32849
user32849

Reputation: 649

Somewhat unintuitivly, this works by adding empty lines:

-i, --input-type
:    Specify the input type. Choices include

     1. float
         * signed
         * unsigned
     2. integer
     3. bool

     Other data types will cause an exception. You should therefore
    be very careful what you put in here.

-o, --output
:    The name of the output file.

Upvotes: 2

Waylan
Waylan

Reputation: 42547

I suspect you are not going to be able to find a Markdown format that also works as a man page. The two formats are not very compatible.

For starters, In Markdown, anything indented by four spaces or more is a code block. In other words, the text is passed through as literal text and not parsed as Markdown. This means you cannot indent the text under each flag.

Second, you need to include a blank line between different block level elements. The rules are a little fuzzy on this and different Markdown parsers will behave slightly differently, but to get consistent results, it is best to always include a blank line.

Finally, to differentiate the flags from their descriptions you might want to make them headers. And you should probably wrap the flags in inline code spans to preserve the formatting, etc.

Your Markdown would then look something like this:

## `-i`, `--input-type`

Specify the input type. Choices include

1. float
    * signed
    * unsigned
2. integer
3. bool

Other data types will cause an exception. You should therefore
be very careful what you put in here.

## `-o`, `--output`

The name of the output file.

Which would render like this:

-i, --input-type

Specify the input type. Choices include

  1. float
    • signed
    • unsigned
  2. integer
  3. bool

Other data types will cause an exception. You should therefore be very careful what you put in here.

-o, --output

The name of the output file.

Alternatively, you could make the flags an outer list with the content nested inside. This might give you formatting closer to what you want as plain test:

* `-i`, `--input-type`

    Specify the input type. Choices include

    1. float
        * signed
        * unsigned
    2. integer
    3. bool

    Other data types will cause an exception. You should therefore
    be very careful what you put in here.

* `-o`, `--output`

    The name of the output file.

And that renders as:

  • -i, --input-type

    Specify the input type. Choices include

    1. float
      • signed
      • unsigned
    2. integer
    3. bool

    Other data types will cause an exception. You should therefore be very careful what you put in here.

  • -o, --output

    The name of the output file.

While either will provide nice results from the Markdown, you probably don't want either as a man page. The best solution would most likely be to write (or find) some script which converts between the man page and Markdown.

Upvotes: 0

Related Questions