postmodern / kramdown-man Goto Github PK

Should be able to achieve 70-80% documentation coverage.

A man link containing a dot seems to be broken:

See [shard.yml](man:shard.yml(5)) for more information.

See
.BR shard for more
information\.

We don't use Kramdown on our sites, we prefer Redcarpet & Github-Markdown through html-pipeline.
If you need help tell me where I can start and I'll be happy to help.

Bold text at the beginning of a text block creates a hanging left indentation (.HP) in roff output:

**shards** requires the presence of a `shard.yml` file in the project
folder (working directory). This file describes the project and lists
dependencies that are required to build it.

.HP
\fBshards\fP requires the presence of a \fBshard.yml\fR file in the project
folder (working directory)\. This file describes the project and lists
dependencies that are required to build it\.

That seems unexpected to me. And .HP is deprecated.

Indented paragraphs end up retaining their indentation, but the paragraph is word wrapped by man.

Let's run with that rake task, since it never got merged into md2man.

Support converting typographic_sym elements. Kramdown will automatically parse certain sequences of characters into HTML entities.

doc = Kramdown::Document.new("-- Mr. Smith")
doc.root.children[0].children
# => [<kd:typographic_sym :ndash nil>, <kd:text " Mr. Smith" nil>]

Add more example syntax to man/kramdown-man.1.md and the README.

More precisely, it would be great if triple backtick code blocks were to be parsed correctly.
I don't know ruby, but i suspect, it would be relatively easy to add using GFM Parser.

It would be nice to disable the generated by. For sure we will love to give credit to your project on our site but having it on every manpage generated for our docs can just get in the way. I understand the the anger that might be caused by that logic but if we all had to comply with that we would all have Generated by "Insert guy who originally created the first modern processor as we know it".

Add a Kramdown::Man::CLI class and move CLI logic out of bin/kramdown-man.

http://nixdoc.net/man-pages/Linux/man7/mdoc.samples.7.html#Tagged%20Lists%20and%20Columns

It is somehow nicer.

Support detecting multiple options in tagged paragraphs:

`-f`, `--foo`
  The foo option

Which parses as:

[<kd:p nil [<kd:codespan "-f" nil>, <kd:text ", " nil>, <kd:codespan "--foo" nil>, <kd:text "\n\tThe foo option" nil>]>]

According to the documentation definition lists (and tables) are not supported even if kramdown does support it.

Instead of trying to identify paragraphs that start with a code, em, or strong element and who's first line isn't indented but the following lines are indented, kramdown-man should just use normal markdown definition lists. This will entail adding convert_dt and convert_dd methods, which outputs a .TP modifier, followed by the term and the definition body.

Current Syntax

`-o`, `--option`, *VALUE*
  Description of the option goes here.
  
...

New Syntax

`-o`, `--option` **VALUE**
: Description of the option goes here.

...

Desired Roff Output

.TP
\fB-o\fR, \fB--option\fR \fBALUE\fP
Description of the option goes here.