nixos/systemd: document what scriptArgs is for

[ncfavier]

Related to #154123, I guess

[ncfavier]

Would be nice to have manpage links working in options.html. I think we could

• split out the manpage → URL mapping into a JSON file or whatever lua can parse
• duplicate the link-unix-man-references.lua logic here

[pennae]

looks good. as for linking in options.html, we could move the manpage reference table to a special doc attribute that generates an MD footer with link targets? that way the renderers could remain agnostic and html output can get automatic linking with no extra effort.

[roberth]

Neat.

[roberth]

Actually it doesn't seem to work? When I render the manual and load the options page, I don't see any replacements. Maybe this operates on the docbook, which is structured?

    def manpage(self, page, section):
        title = f"<refentrytitle>{escape(page)}</refentrytitle>"
        vol = f"<manvolnum>{escape(section)}</manvolnum>"
        return f"<citerefentry>{title}{vol}</citerefentry>"

[ncfavier]

Yep, see #207268 (comment)

[roberth]

Ah I see. I thought you implemented that. I should've clicked the link in that comment.

[roberth]

May need a fix

[roberth]

Actually it doesn't seem to work? When I render the manual and load the options page, I don't see any replacements. Maybe this operates on the docbook, which is structured?

    def manpage(self, page, section):
        title = f"<refentrytitle>{escape(page)}</refentrytitle>"
        vol = f"<manvolnum>{escape(section)}</manvolnum>"
        return f"<citerefentry>{title}{vol}</citerefentry>"

[ncfavier]

@pennae that would require changing the manpage syntax to something like [systemd.unit(5)], unless i'm misunderstanding? But then other documents would have to append the footer everywhere, which seems burdensome, unless there's an easy way to do that with pandoc?

[pennae]

that would require changing the manpage syntax to something like [systemd.unit(5)], unless i'm misunderstanding?

not necessarily. once we actually render from markdown to html/manpages/… directly each renderer can process the manpage tag as appropriate, the default being "the traditional text representation" and the html renderer overriding that to wrap it in a link.

But then other documents would have to append the footer everywhere

was thinking about only option docs for that suggestion. if the manpage maps are json the option docs build process could load them and set them as a default map for eg documentation.nixos.options.manpageLinks, which would be formatted and appended to the markdown document before rendering. but that's all a long way out anyway :(

[ncfavier]

not necessarily

Well, if we want this to work with a footer (I'm assuming you're talking about https://pandoc.org/MANUAL.html#reference-links), the manpage references must have that shape, so we'd need a step that converts {manpage}`foo` to [foo] in Markdown, before we append the footer and render to HTML. But at that point it seems easier to just do the conversion from {manpage}`foo` to <a href=...>foo</a> directly, as a filter in the Markdown → HTML pipeline (as is currently done in the Markdown → DocBook pipeline).

[ncfavier]

Would be nice to have manpage links working in options.html.

Done in #208762