feat! rewrite to be for ROFF, not manual pages

[larswirzenius]

While looking at generating manual pages from clap:App (see, for example, https://github.com/clap-rs/clap/pull/3174), I reviewed the roff crate. I found several things that I think could be improved:

• It mixes concerns. Some of the crate functionality is aimed at generating source for manual pages, and not just generic documents using the ROFF language. This both makes the crate less useful (it's not suitable unless one uses the -man macro package for troff), and harder to use (it hard codes some assumptions about manual pages, such as what arguments .TH gets).
• The manual section is an integer, which prevents a suffix such as in the openssl(1ssl) manual page.
• There's no support for sub-sections.
• There's no escaping of text lines with leading dots. ROFF interprets them as control lines. If one is creating ROFF from, say, Markdown, one needs to handle the leading dots oneself.
• In general, the user of the crate needs to understand how to quote or escape things to avoid invoking ROFF accidentally.
• There's little to no documentation of the API.

This commit introduces a complete rewrite to address my concerns. I'm afraid I could not come up with a reasonable sequence of small changes to get where I want the crate to be. The changes are radical, and break backwards compatibility, so the version number will need to be bumped.

A summary of the changes:

• The crate now aims at generic ROFF support. There is no trace of manual page support anymore. For example,struct Roff knows nothing about manual page metadata, and there is no longer any support for sections.
• Control and text lines are given to a Roff explicitly, and handled separately, to get various kinds of escaping and quoting correct.
• If generating manual pages, a section is done by creating an "SH" control line, and then text lines for the content. Any higher level abstraction should, I think, be done above the level of the roff crate.
• Text lines consist of inline elements, to represent text in fonts.
• Text lines with leading periods are handled by inserting an invisible glyph.
• The Troffable trait is gone, as it didn't seem useful anymore.
• All public symbols have rudimentary documentation.
• There's some unit testing. The pre-existing manual page rendering test is kept, with no change to the expected output, though the code to generate is adapted to the new API.

[epage]

feat! rewrite to be for ROFF, not manual pages

FYI the lint commit failed because there is a missing : after the !. As the failure says, I can take care of it in the end of you don't feel like it.

[epage]

Going to go ahead and merge.

• Builder is unresolved
• There are some cases where a fix was applied in one place but not others

Going to do a quick PR after this to fix some things up but just wanting to unblock progress on clap_man

[sondr3]

I'll close my own PR here then, thanks for helping out @larswirzenius :smile:

[epage]

https://github.com/rust-cli/roff-rs/pull/16

[epage]

roff 0.2 has been released.