postmodern / kramdown-man Goto Github PK

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.

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

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

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.

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

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

It is somehow nicer.

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

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

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

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.

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

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

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

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.

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