Support for custom sections?

[codesections]

As discussed in #1, a man page traditionally has several different sections beyond the few that man currently supports. I agree that, long-term, it would be best for man to support a larger number of those sections. Supporting a list section directly would allow man to provide a higher abstraction over that section and would guide crate authors towards including relevant/helpful/traditional sections.

However, I believe man should also support custom sections. In the short term, this would allow users to include any of the sections listed in #1, even if they need to operate at a bit lower level of abstraction/don't have access to the same degree of prewritten formatting. Longer term, including custom sections would still be useful to users who want to include sections beyond those we chose to support.

As an example of the later, I have seen many man pages that include a copying section, which isn't one of the sections listed in #1. Many users might want to include that section, and a custom section command would let them do so.

If no one objects or has a different suggestion, I will work on a PR for custom sections.

[yoshuawuyts]

@codesections I agree having custom sections would be grand! Do you have an idea of what the API would look like that you could share?

[codesections]

I was imagining a very simple API: the ability to create a custom section, give it a name, and then give it one or more paragraphs of text. (Basically, this would just create a very thin abstraction over the underlying roff crate, but would be a bit more focused on the semantics instead of the literal formatting.) Using this API to create the "regex syntax" section from ripgrep's man page would look like this:

Manual::new("ripgrep")
// [snip]
    custom("regex syntax")
        .paragraph("ripgrep uses Rust’s regex engine by default, which documents its syntax: https://docs.rs/regex/*/regex/#syntax")
        .paragraph("ripgrep uses byte-oriented regexes, which has some additional documentation: https://docs.rs/regex/*/regex/bytes/index.html#syntax")
        .paragraph("To a first approximation, ripgrep uses Perl-like regexes without look-around or backreferences. This makes them very similar to the "extended" (ERE) regular expressions supported by egrep, but with a few additional features like Unicode character classes.")
        .paragraph("If you're using ripgrep with the --pcre2 flag, then please consult https://www.pcre.org or the PCRE2 man pages for documentation on the supported syntax.");
        

This would render:

REGEX SYNTAX
       ripgrep uses Rust’s regex engine by default, which documents its syntax: https://docs.rs/regex/*/regex/#syntax

       ripgrep uses byte-oriented regexes, which has some additional documentation: https://docs.rs/regex/*/regex/bytes/index.html#syntax

       To a first approximation, ripgrep uses Perl-like regexes without look-around or backreferences. This makes them very similar to the "extended" (ERE) regular
       expressions supported by egrep, but with a few additional features like Unicode character classes.

       If you’re using ripgrep with the --pcre2 flag, then please consult https://www.pcre.org or the PCRE2 man pages for documentation on the supported syntax.

The advantage of this API is that it would be very simple—both to write and, more importantly, to use. However, one disadvantage is that it would not allow for custom formatting for the custom section (e.g., to have command examples printed in bold). That could be addressed by having a separate API for more advanced formatting, though (or by adding in additional sections for the sections that need more detailed formatting, such as an examples sections).

[yoshuawuyts]

@codesections ohh, yeah I can get behind that design!

However, one disadvantage is that it would not allow for custom formatting for the custom section (e.g., to have command examples printed in bold)

Perhaps we could re-export the roff crate so people can roll their own if they want to?