Add a manpage backend

[pjanx]

https://asciidoctor.org/docs/user-manual/#man-pages

A subset is sufficient to document almost everything: bold, italics, links, section headers, definition lists, literal blocks.

Apparently relates to #581.

scdoc is a good and brief resource--targeting the mdoc macro package would be hard because it uses a lot of semantic markup but the standard-to-Linux man package is rather straight-forward. Make sure to handle sentence spacing correctly (I'm in favour of letting roff double space, unlike Drew).

[pjanx]

I almost have an MVP. Currently blocking on #800.

[xcoulon]

I almost have an MVP. Currently blocking on #800.

oh, a PR for manpage support would be great! 🤩

[pjanx]

Yeah, I'm in the situation where 80% of time will be spent on 20% of details. I'm trying to make it as small as possible.

[pjanx]

If you want to help, this needs to be abstracted away, manpages have .[1-9][a-z] extensions defined by section 0 heading:

		outname := strings.TrimSuffix(path, filepath.Ext(path)) + ".html"

The filename isn't known until parsing (or generation). What do?

[xcoulon]

If you want to help, this needs to be abstracted away, manpages have .[1-9][a-z] extensions defined by section 0 heading:

		outname := strings.TrimSuffix(path, filepath.Ext(path)) + ".html"

The filename isn't known until parsing (or generation). What do?

I'm not sure I'm following you. Maybe you could create a PR in draft mode and point me to where you have blockers?

[pjanx]

foo.adoc:

= foo(1)
== Name
foo - does things

asciidoctor -b manpage foo.adoc

This produces file foo.1. The Convert function is an unusable interface (also for EPUB or whatever).

[pjanx]

Well, it could probably still be used if the extension were placed in the Metadata struct but you'd have to buffer the output or create a temporary file up first (which isn't a bad idea anyway, to use atomic rewrites).

[xcoulon]

foo.adoc:

= foo(1)
== Name
foo - does things

asciidoctor -b manpage foo.adoc

This produces file foo.1. The Convert function is an unusable interface (also for EPUB or whatever).

ok, I see what you mean now. Or you could use the -o flag to specify the output, maybe?

[xcoulon]

Well, it could probably still be used if the extension were placed in the Metadata struct but you'd have to buffer the output or create a temporary file up first (which isn't a bad idea anyway, to use atomic rewrites).

I'm fine with adding this kind of feature for manpage docs, it shouldn't be too hard, as you suggested, to buffer or write in a temp file and rename it afterwards

[pjanx]

I'll return to this sooner or later but right now I'm postponing it.

[pjanx]

If anyone happens to need this feature, I've impulsively created a simplified AsciiDoc to man page converter in AWK for a basic subset of the language (I'm using it as a fallback for 1, 2, 3, 4, 5, 6). Perhaps it works better than it should.

Thus, even though it should remain fairly easy to teach libasciidoc how to do it properly, I'm no longer particularly invested. (To make use of it, I'd additionally need to do something about #187.)