Support for custom sections? about man HOT 3 CLOSED

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

from man.

@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?

from man.

@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?

from man.