Conversation

Notices

1. Embed this notice
   Hugo 雨果 (whynothugo@fosstodon.org)'s status on Wednesday, 09-Apr-2025 09:27:19 JST Hugo 雨果

   What would you use to create high quality man pages?

   scdoc and asciidoc don't support cross-references.

   I'm kind of starting to see why some authors just write raw troff and commit that, but I'd like something more human-friendly if possible.

   • Embed this notice
     Haelwenn /элвэн/ :triskell: (lanodan@queer.hacktivis.me)'s status on Wednesday, 09-Apr-2025 09:27:19 JST Haelwenn /элвэн/ :triskell:

     in reply to
     @whynothugo Maybe mdoc would be friendlier?
     (So far I've just used mdoc and nearly ignored troff/man)
   • Embed this notice
     Haelwenn /элвэн/ :triskell: (lanodan@queer.hacktivis.me)'s status on Wednesday, 09-Apr-2025 09:39:45 JST Haelwenn /элвэн/ :triskell:

     in reply to

     • anna

     @navi @whynothugo rc-*.8 are all mdoc, unsurprising as mdoc comes from BSD and OpenRC has some BSD heritage.

     See mdoc(7) for the format.

   • Embed this notice
     anna (navi@social.vlhl.dev)'s status on Wednesday, 09-Apr-2025 09:39:46 JST anna

     in reply to

     • Haelwenn /элвэн/ :triskell:
     @lanodan @whynothugo openrc has some hand written (nroff? man? troff? idk) pages and i *hate* editing them so hard, i was considering pushing for scdoc upstream, iirc there was a patch in the ml for it about the cross-referencing?
     
     i wonder if mdoc is any less bad than the current openrc pages tho
   • Embed this notice
     Haelwenn /элвэн/ :triskell: (lanodan@queer.hacktivis.me)'s status on Wednesday, 09-Apr-2025 10:03:53 JST Haelwenn /элвэн/ :triskell:

     in reply to

     • anna

     @whynothugo @navi Can .Xr be used in man(7) pages?

     Because as far as I know it's an mdoc(7) exclusive and I don't think you can mix two sets of troff macros.
     (Although mdoc(7) is a bit more standalone since mandoc, but groff as used by manpagers like man-db on most Linuxes also supports mdoc(7) so still somewhat a set of troff macros)

   • Embed this notice
     Hugo 雨果 (whynothugo@fosstodon.org)'s status on Wednesday, 09-Apr-2025 10:03:54 JST Hugo 雨果

     in reply to

     • Haelwenn /элвэн/ :triskell:
     • anna

     @navi @lanodan The mention on the list was my own: https://lists.sr.ht/~sircmpwn/public-inbox/%3Ca31b8cd7-079b-4a7f-b6c5-01d90b5bd08f@app.fastmail.com%3E

     I tried to produce a patch but failed miserably. A larger refactor is required. If you want to give it a shot, it would be most appreciated!

     scdoc is also missing support for Sx, which allows linking to another section in the page (man pagers merely style the link, but HTML renders will insert the appropriate anchors). This one is less important, but nice to have.

   • Embed this notice
     Haelwenn /элвэн/ :triskell: (lanodan@queer.hacktivis.me)'s status on Wednesday, 09-Apr-2025 10:13:07 JST Haelwenn /элвэн/ :triskell:

     in reply to

     • anna

     @whynothugo @navi > It's the format into which all man pages are compiled.

     It's absolutely not, check a manpage from say a GNU project if you want to see what a man(7) document looks like.

     In fact in practice it can even be the other way around as mandoc ships with -Tman to render into a man(7) document for purely legacy purposes.

   • Embed this notice
     Hugo 雨果 (whynothugo@fosstodon.org)'s status on Wednesday, 09-Apr-2025 10:13:08 JST Hugo 雨果

     in reply to

     • Haelwenn /элвэн/ :triskell:
     • anna

     @lanodan @navi Indeed, they are mdoc. If I understand correctly, mdoc is a subset of roff with some additional macros. It's the format into which all man pages are compiled.

     See: https://man.openbsd.org/mdoc.7

   • Embed this notice
     Hugo 雨果 (whynothugo@fosstodon.org)'s status on Wednesday, 09-Apr-2025 12:06:56 JST Hugo 雨果

     in reply to

     • Haelwenn /элвэн/ :triskell:
     • anna

     @lanodan @navi I see, I'd quite misunderstood the situation.

     Inspecting the raw man page for rc-update and sway I see that they are slightly different (being mdoc and man respectively). man(1) doesn't care about the difference and renders both without issues.

     mdoc(7) is definitely more readable than man(7). The description for man(7) refers to it as "legacy formatting language for manual pages".

     Haelwenn /элвэн/ :triskell: likes this.
   • Embed this notice
     Hugo 雨果 (whynothugo@fosstodon.org)'s status on Wednesday, 09-Apr-2025 12:08:11 JST Hugo 雨果

     in reply to

     • Haelwenn /элвэн/ :triskell:
     • anna

     @lanodan @navi I wish man(1) would support things like following references.

   • Embed this notice
     Haelwenn /элвэн/ :triskell: (lanodan@queer.hacktivis.me)'s status on Wednesday, 09-Apr-2025 12:08:11 JST Haelwenn /элвэн/ :triskell:

     in reply to

     • anna
     @whynothugo @navi Yeah, often wished it would work more like lynx/w3m/… in that regard, specially when mdoc(7) has all the semantics you need for this.
   • Embed this notice
     anna (navi@social.vlhl.dev)'s status on Wednesday, 09-Apr-2025 12:49:22 JST anna

     in reply to

     • Haelwenn /элвэн/ :triskell:
     @lanodan @whynothugo it makes people complaining about how "manpages lack things necessary to be modern documentation" because, they have most of what you need-- but man.1 still wants to render it statically like it's the 80s
     
     like we don't even have reflow on terminal resize ffs
     Haelwenn /элвэн/ :triskell: likes this.
   • Embed this notice
     Hugo 雨果 (whynothugo@fosstodon.org)'s status on Thursday, 10-Apr-2025 01:12:57 JST Hugo 雨果

     in reply to

     • Haelwenn /элвэн/ :triskell:
     • anna

     @navi @lanodan We _could_ write a brand new man(1) which reads both mdoc(7) and man(7) but has support for links and reflowing. I'll put it at the end of my TODO list, I might have time in 735 years.

     Haelwenn /элвэн/ :triskell: likes this.
   • Embed this notice
     Haelwenn /элвэн/ :triskell: (lanodan@queer.hacktivis.me)'s status on Thursday, 10-Apr-2025 01:17:14 JST Haelwenn /элвэн/ :triskell:

     in reply to

     • anna
     @whynothugo @navi I don't think it needs to be brand new though?
     Specially when I think the pager could just be $BROWSER instead so you get UI and semantic format for free.