~sircmpwn/public-inbox

3 2

scdoc: emitting Xr "link" macros

Details
Message ID
<a31b8cd7-079b-4a7f-b6c5-01d90b5bd08f@app.fastmail.com>
DKIM signature
pass
Download raw message
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
Details
Message ID
<D67ZO9S4OVYN.4KFV178YOW5F@cmpwn.com>
In-Reply-To
<a31b8cd7-079b-4a7f-b6c5-01d90b5bd08f@app.fastmail.com> (view parent)
DKIM signature
pass
Download raw message
Sure, I like that syntax.
Details
Message ID
<c2wljeee5cimzlznhbpgtexcedmmie26cmparpumozfbeoc3hz@h67domi7gvpq>
In-Reply-To
<D67ZO9S4OVYN.4KFV178YOW5F@cmpwn.com> (view parent)
DKIM signature
pass
Download raw message
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
Details
Message ID
<D6DDUHHTN17L.7N5B1WU85DXV@cmpwn.com>
In-Reply-To
<c2wljeee5cimzlznhbpgtexcedmmie26cmparpumozfbeoc3hz@h67domi7gvpq> (view parent)
DKIM signature
pass
Download raw message
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.
Reply to thread Export thread (mbox)