On Apr 22 09:29:53, [email protected] 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, [email protected] 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 [email protected]
