Documentation: man pages

[AladW]

• man-pages(7) structure
• convert to .groff
• aurbuild
• aurchain
• aurqueue
• aursearch
• aursift
• aursync
• repofind
• repoman

See also: #1

[Earnestly]

Writing manuals in plain groff using the man macros is actually quite simple, it's just another markup language. Unless you really need some kind of universal markup language to generate documentation for every conceivable need, I'd not bother with the additional dependency.

A simple example I did: https://github.com/Cloudef/orbment/blob/master/orbment.1.in

If you have the document text, such this, I can annotate it with needful groff macros.

[AladW]

Thanks for the hint and examples. With some experimenting, I added the first man page with 58ecf1f

With groff -Tascii -man it looks like this:

AURSIFT(1)                  General Commands Manual                 AURSIFT(1)



NAME
       aursift - filter packages in the Arch Linux repositories

SYNOPSIS
       aursift <operation> [targets]

DESCRIPTION
       Invoking  aursift  involves  specifying an operation with any potential
       options, and targets to operate on. A target is usually a package name,
       or a (space-separated) string of package base and package version. Tar-
       gets can be provided on stdin.

OPERATIONS
       -S  Check if pkgname is in the official Arch  Linux  repositories,  and
           print  it  to  stdout  if  not. Virtual packages, when found, are
           solved and printed to stderr.

       -U  Compare pkgbase pkgver against packages from any configured reposi-
           tory. Names of updated package bases are printed on stdout.

SEE ALSO
       pacsift(1), expac(1)



                                                                    AURSIFT(1)

I wasn't too sure on the actual text, so I took pacman(1) as a baseline. Thoughts?

[Earnestly]

Use .TH AURSIFT 1 2016-03-30 AURUTILS for the title, you could add the final field which is the name of the manuals, e.g. "General Commands Manual", but since that seems like a fine name, you can leave it out.

Add an AUTHORS section:

.SH AUTHORS

.MT https://github.com/AladW
Alad Wenter
.ME

Change <operation> to -SU or keep it consistent with the usage: ... synopsis.

Instead of .TP use .RS and .RE.

You could also wrap those lines to 80 columns or so just to make it easier to view since roff is a proper typesetter unlike HTML which doesn't know how to deal with linebreaks.

The description seems a bit vague and could be made simpler. I mean you don't need to talk about invoking commands and how commands work, just focus on explaining what aursift itself does, such as the second half which explains what [targets] is.

You've marked [targets] as optional, but are they? A general approach is that [] indicates optionality, while plain text indicates that it's mandatory. There's no need for <> imo (and plan9 doesn't use them).

PS: pacman's manuals are probably not the best examples to follow, man-pages stuff should be decent and plan9's (i.e. from plan9port) can also be good.

[AladW]

For <operation>, as the two operations are exclusive I've put each on one line, without brackets. Maybe usage: needs similar adjustments?

For .RS, the following:

.B \-S
.RS
Check if
.I pkgname
is in the official Arch Linux repositories, and print it to stdout if
not. Virtual packages, when found, are solved and printed to stderr.
.RE

ends up like:

-S
      Check if pkgname is in the official Arch Linux repositories, and print it to stdout
      if not. Virtual packages, when found, are solved and printed to stderr.

I'm unsure on the extra break over .TP, since I only have a short option (acid(1) is similar, though it has .TP over .TP 4).

I'll continue work on the wording, thanks.

[Earnestly]

It doesn't really matter that they're exclusive, however you could then use something more like usage: aursift [-S pkgname] [-U target] where you can change the argument names to something more appropriate which you can directly reference in the description.

The .RS/.RE output is correct. Keep in mind that groff is rendering to multiple terminal sizes, .TP alone will not be nice at shorter descriptions.

Btw, you can use inline markup using \f. For example, This is \fIitalic \Rand this is roman if you find constantly breaking lines for markup to be annoying.

PS: Plan9 uses nroff which might be different and plan9port may have done some mechanical conversion. I only mentioned plan9 for their SYNOPSIS style. Likewise there are lots of manuals out there that are generated and use odd man package macros.

[runical]

OK, so as I promised on the Arch forums, I'm working on the documentation (currently in markdown). I have short man pages for aursync and aurbuild at the moment.

I also have two questions about aursync:

• The -n flag. It translates to noprepare, so I assume that it somehow stops preparation, but what does that concretely mean in this case?
• The -i flag is mentioned in the help, but does not seem to have an actual function other than matching the *) clause when parsing. Is this intended or is it extraneous?

[AladW]

If noprepare is not set, then version checks are done. In practice this means:

• Take "pkgname pkgver" pairs from the RPC (alphabetically sorted), and pass those on to aursift -U. The result is a list of package names which are updated in the local (or official) repos. Side note: I should rename pair_sync to list_sync on that regard.
• Replace pkgname with pkgbase in this list. You want the build queue to only contain pkgbase - clone dirs are named after pkgbase, and you want to cd to it for later builds.
• Take the existing pkgbase queue (queue_base), and do an inverse match from the above list. While queue_base is in total order, and the list is not, this doesn't matter as grep keeps the order of the target file, i.e. queue_base. The result is called queue_new.

In short, prepare checks package versions to see which packages already have the same version of the AUR package, or newer. Those that are, are removed from the build queue.

What noprepare does is simply disable this step, by copying the original pkgbase queue (queue_base) to queue_new.

About the -i flag, yeah it's a left-over from #88 (see #94 for a new approach).

[Earnestly]

In short, prepare checks package versions to see which packages already have the same version of the AUR package, or newer. Those that are, are removed from the build queue.

This may have implications for packages that need relinking

[AladW]

True enough. The version check idea was introduced with #28, to avoid building packages twice. I'm not sure what would be the best approach here. See also #85 and #97.