scdoc currently does not support emitting the Xr, which is defined as[1]:
> Xr: cross reference to another manual page
This macro has a semantic meaning, but is also converted into a link when man
pages are rendered as HTML pages, as can be seen online in websites like
https://man.openbsd.org/
I'd like to extend scdoc with the capability to emit these macros, so that man
pages can include references to each other. I believe that a sane syntax for
this is:
The [scdoc(5)] command generates pages in [man(7)] style roff.
Any thoughts on this? I don't believe that this syntax should conflict with any
existing usages.
Cheers,
[1]: https://man.openbsd.org/mdoc.7#Sections_and_cross_references
--
Hugo
I implemented this in parse_text, but it only works for mid-line references.
Lines that start with [ are handled via parse_table, which panics if it turns
out that the line isn't a table.
This is the same reason that currently lines can't start with [.
I could refactor parse_table; when the input starts with [ but isn't a table,
put chars back in the stack, and assume they are a link or regular text.
This should be a huge refactor, but would also allow regular lines to start
with [. However, subtly miss formatted tables would render as non-table rather
than panic (I'm not sure if this is a good thing or not).
Touching the table-related code sounds like a far bigger challenge. Any
thoughts?
--
Hugo
Hm, interesting problem. I think it would make sense to add a small
amount of readahead to disambiguate tables and paragraphs with links,
though it does indeed imply some refactoring.