add template for man page to snippets

[mojavelinux]

Man pages require a special document structure. This snippet gets you started.

[mojavelinux]

Also removed the file too.adoc that accidentally got committed.

[nicorikken]

This functionality and it's proper usage was new to me. The use-case itself not of course 😉 A very nice showcase of the power of Asciidoc, having to define name and author only once, whilst it is rendered multiple times. Here is a basic example I tried to test this snippet, based on the example in the Asciidoctor user manual.

= {name}(1)
Andrew Stanton
v1.0.0
:doctype: manpage
:name: eva
:man manual: User Commands
:man source: {revnumber}

== NAME

{name} - analyzes an image to determine if it's a picture of a life form

== SYNOPSIS

*{name}* ['OPTION']... 'FILE'...

== OPTIONS

*-o, --out-file*::
  Write results to file.

== EXIT STATUS

*0*::
  Success.

*1*::
  Failure.

== COPYRIGHT

Copyright \(C) {author}.

This is free software.
See the source for copying conditions.

Renders like:

I think this can be merged.

[ldez]

Cool feature!

Only one question: it's a real commons case?

• If yes I'm OK for the merge.
• If not I'm prefer see this feature in an another package (ie: asciidoc-writer)

[mojavelinux]

Only one question: it's a real commons case?

Very common for teams that use AsciiDoc primarily for man pages, such as the git project. It's also one of the trickiest document structures to type from scratch, so the template here saves tons of time. My hope is that it also means people will make more man pages, which we need in this world.

[mojavelinux]

having to define name and author only once, whilst it is rendered multiple times.

Indeed, this is one of the main DRY powers of AsciiDoc.

As it turns out, it is possible to have the template edit the same text in multiple places by using the syntax ${1:name} multiple times in the template. However, there's no reason to do this since AsciiDoc already has support for reusable text. But something to keep in mind for the future.

[ldez]

@mojavelinux Can you rebase ?

[mojavelinux]

You bet!

[mojavelinux]

Done!