Rendered HTML contains nonsensical H1 element w/ structured header/footer data for groff

[nfagerlund]

The initial H1 of a md2man document often contains something bizarre like puppet-agent 8 "SOME DATE" "Puppet Labs LLC" "Puppet Manual". Although md2man-roff treats this as structured data (according to the inscrutable rules of .TH) and arranges the component parts accordingly, the HTML renderer just passes it through undigested.

I'm not sure what the ideal arrangement of this metadata in a rendered HTML fragment should be -- could even be that the desired format is too idiosyncratic and site-specific to impose something on everyone. I AM pretty sure that the raw ready-for-.TH text should never be put where users can see it.

Fixing this may require some design and configurability. Alternately, a good-enough approach might involve processing the header, putting the data in more-or-less correct places in the rendered HTML with appropriate classes, and providing methods to override so users who really need something different can just subclass the HTML renderer or something.

(As a sidenote, I'm not sure just passing on the format requirements of the .TH directive to the writer is the best way to collect that metadata.)

[sunaku]

Interesting. Yes, we could parse the initial H1 before emission as a set of stylable HTML spans in md2man-html(1). However, I'm not convinced that the initial H1's inheritance of .TH syntax is a bad thing because [1] it's the simplest thing to do and [2] it puts the writer in control of how the .TH request is specified in the output of md2man-roff(1).

For writers coming from Roff to md2man, I would think that said syntax inheritance is rather straight-forward. However, for writers coming from Markdown to md2man, I agree that said syntax inheritance can be rather unnerving---partly because md2man(5) currently does not document the inherited syntax of the initial H1. 😅

[nfagerlund]

Fair nuff! A tool I used to use would sometimes cause problems by trying to abstract the roff behavior TOO much, so I get where you're coming from. I'd be satisfied with documenting the format + munging similarly in HTML and roff.

[sunaku]

Hey @nfagerlund, I have fixed these issues in v2.1.0. ✨

Please reopen this issue if you find it inadequate. Cheers! 🍰