Migrating the guide to AsciiDoc

[Jan Stary]

On Apr 22 09:29:53, mojca at macports.org wrote:
> As requested during yesterday's meeting, here's the result of
> automatic conversion of our guide from xml (docbook) to asciidoc:
> 
>     https://github.com/macports/macports-guide/tree/master/guide/adoc
> 
> This was initially explored by Aljaž and gives quite nice results
> out-of-the-box,

Thank you. Any format is better than xml,
and any tool is better than docbook.

> but there are still some issues with conversion that
> will have to be addressed either by fixing docbookrx itself or
> manually.
> 
> If anyone is willing to help in the process, your help will be appreciated.

Is asciidoc what the user is upposed to read directly, as in e.g.
https://github.com/macports/macports-guide/blob/master/guide/adoc/installing.adoc
or is that considered an "internal" format to be ultimately converted
to html and put on a web page such as https://guide.macports.org/
where the user will read it?

On Apr 22 11:39:23, raimue at macports.org wrote:
> AsciiDoc is both the name of the format and also the name of the
> original reference implementation in Python, but development on that
> ceased a few years ago. AsciiDoctor is an alternative implementation in
> Ruby and actively being developed.

Which one produced the current adoc from of the xml guide?


The Plan section says

 First convert .adoc files back to docbook .xml format
 and use the existing toolchain to generate the html pages
 (to avoid further delays).

That makes no sense to me: why convert back?
Cannot html pages be generated from adoc directly?
(And if so, why not use the original xml?)

> We are already using the AsciiDoc format for our man pages,

Manpages are supposed to be written in mdoc(7), the language of
manpages, just like e.g. /usr/share/man/man1/ls.1 is.

The current port-* manpages are horrible
(not talking about content, but markup).

Look at e.g. port-diagnose.1; read it, line by line.
Note the 2008 workarounds to debian bugs.
Note the 2009 workarouns to GNU roff.
Note the pointless low-level roff(7) tweaks.

Then read the port-diagnose.1 below, written in mdoc(7).
Which one is cleaner, simpler, more readable, more writable, shorter?

I offer to rewrite them.

	Jan


.Dd April 23, 2018
.Dt PORT-DIAGNOSE 1
.Os
.Sh NAME
.Nm port diagnose
.Nd detects common issues with macports
.Sh SYNOPSIS
.Nm port
.Ic diagnose
.Op Fl -quiet
.Sh DESCRIPTION
.Nm port
.Ic diagnose
will check a list of common issues that could
affect the user of MacPorts in one way or another.
If any issues are found, a warning will be
shown to the user included with a possible fix.
.Pp
With the
.Fl -quiet
option, only warnings and errors are displayed.
.Sh SEE ALSO
.Xr port 1
.Sh AUTHORS
.An Kyle Sammons Aq Mt ksammons at macports.org