Re: Migrating the guide to AsciiDoc
On 21.02.20 21:05, Rainer Müller wrote: > On 17.02.20 23:13, Mojca Miklavec wrote: >> I didn't yet check how the latest conversion looks like, so I cannot >> really make a good informed decision, but I would vote for proceeding >> with .adoc. > > For comparison, I just put the AsciiDoc based guide online here: > https://guide-test.macports.org/ Because of a misconfiguration in the CDN, the official guide was pulled from this test version over the weekend. Sorry for that, I did not expect the CDN would use this domain. However, there was only one report on IRC because of this and that was only because the chunked version was missing and some links were broken. That must mean the quality is already good enough. ;-) Anyway, I just updated the guide-test domain once again to also include the chunked version of the guide. > [...] > The known steps that will need manual work are documented here. Please > feel free to add anything else you find in the current guide-test to > this list. Or just sent a reply with feedback. > > https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md Rainer
Re: Migrating the guide to AsciiDoc
On 17.02.20 23:13, Mojca Miklavec wrote: > I didn't yet check how the latest conversion looks like, so I cannot > really make a good informed decision, but I would vote for proceeding > with .adoc. For comparison, I just put the AsciiDoc based guide online here: https://guide-test.macports.org/ > 1.) Could we (at the time when the final migration is done) put the > old fully functional generated manual somewhere for reference, so that > we know what to strive for even after we change the underlying > scripts? > > 2.) Do we already have a process/job in place to generate the docs from .adoc? @Ryan Could you please install the asciidoctor port on the 'jobs-guide' builder? I think this should be the only new dependency. Other than that, we only need to add the 'make guide-fromadoc' target to the build job (or rather, redefine 'make all' accordingly in the Makefile). > I believe that we could crowd-source cleaning the docs at least to > some extent provided that the basics are taken care of. If doing sane > fixes to docbookrx is not feasible in the very near future, it would > help if we could simply freeze the docbook sources (I don't care if > that time is simply now), freeze the manual, generate a new manual > from the .adoc sources in that branch and publish it at a different > temporary URL, so that developers can see the results and maybe even > contribute fixes / PRs without having to get the courage to run the > conversion process themselves. Once the result is somewhat > satisfactory or the decided deadline passes (whichever comes first), > (clean and) merge the branch to master and publish the new manual at > the old URL (and maybe the old one at a different one for comparison > for a limited time period). Some of changes I made to docbookrx are specific to the MacPorts Guide, for example to deal with the XML include structure. I do not think it is worth to try to find a generic solution for that. The known steps that will need manual work are documented here. Please feel free to add anything else you find in the current guide-test to this list. Or just sent a reply with feedback. https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md Rainer
Re: Migrating the guide to AsciiDoc
On Mon, 17 Feb 2020 at 21:05, Clemens Lang wrote: > > Hi, > > On Sat, Feb 15, 2020 at 01:52:44AM +0100, Rainer Müller wrote: > > It has been almost two years... I would like to suggest we finally > > decide on a flag day on which I will do a final conversion of the > > DocBook to AsciiDoc and after that only the AsciiDoc version is kept > > in the repository. All remaining issues can then be worked on in the > > AsciiDoc files. > > > > Please test out the conversion from AsciiDoc to HTML and compare the > > result with the previous DocBook version: > > make guide-fromadoc && open guide/html/adoc/index.html > > > > The README.md file documents known issues and things that will need > > manual work after the final conversion. Feel free to add anything else > > you can spot: > > https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md > > > > If we are still not ready to make the switch, I would like to give up > > this experiment and delete all *.adoc files from the repository as the > > current state seems to be rather confusing for contributors. > > I agree. We should switch and then just fix the issues that are still > open. I think we can live with suboptimal formatting for a while until > somebody has the chance to fix it, especially if it's much easier to fix > due to the more modern asciidoc syntax. I didn't yet check how the latest conversion looks like, so I cannot really make a good informed decision, but I would vote for proceeding with .adoc. 1.) Could we (at the time when the final migration is done) put the old fully functional generated manual somewhere for reference, so that we know what to strive for even after we change the underlying scripts? 2.) Do we already have a process/job in place to generate the docs from .adoc? I believe that we could crowd-source cleaning the docs at least to some extent provided that the basics are taken care of. If doing sane fixes to docbookrx is not feasible in the very near future, it would help if we could simply freeze the docbook sources (I don't care if that time is simply now), freeze the manual, generate a new manual from the .adoc sources in that branch and publish it at a different temporary URL, so that developers can see the results and maybe even contribute fixes / PRs without having to get the courage to run the conversion process themselves. Once the result is somewhat satisfactory or the decided deadline passes (whichever comes first), (clean and) merge the branch to master and publish the new manual at the old URL (and maybe the old one at a different one for comparison for a limited time period). Mojca
Re: Migrating the guide to AsciiDoc
Hi, On Sat, Feb 15, 2020 at 01:52:44AM +0100, Rainer Müller wrote: > It has been almost two years... I would like to suggest we finally > decide on a flag day on which I will do a final conversion of the > DocBook to AsciiDoc and after that only the AsciiDoc version is kept > in the repository. All remaining issues can then be worked on in the > AsciiDoc files. > > Please test out the conversion from AsciiDoc to HTML and compare the > result with the previous DocBook version: > make guide-fromadoc && open guide/html/adoc/index.html > > The README.md file documents known issues and things that will need > manual work after the final conversion. Feel free to add anything else > you can spot: > https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md > > If we are still not ready to make the switch, I would like to give up > this experiment and delete all *.adoc files from the repository as the > current state seems to be rather confusing for contributors. I agree. We should switch and then just fix the issues that are still open. I think we can live with suboptimal formatting for a while until somebody has the chance to fix it, especially if it's much easier to fix due to the more modern asciidoc syntax. -- Clemens
Re: Migrating the guide to AsciiDoc
On 25.04.18 04:35, Rainer Müller wrote: > On 2018-04-22 09:29, Mojca Miklavec 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, but there are still some issues with conversion that >> will have to be addressed either by fixing docbookrx itself or >> manually. > > I fixed some of the issues by slightly modifying the XML. None of these > should change the output produced by DocBook, but help docbookrx to > understand the XML. > > I started to document the issues with the conversion in the README. This > is not exhaustive, please add more things to this list if you spot them. > > https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md > > On one hand, some issues can only be fixed manually once we are sure we > are not going to run docbookrx again. On the other hand, I noticed that > it would be easier to fix other issues in docbookrx instead of > post-processing the *.adoc files. > > However, some of the issues require tweaks to docbookrx that are > specific to the MacPorts guide, as they depend on assumptions how > certain elements are used. > > I pushed some commits with such changes that are specific to the > MacPorts guide to my fork of docbookrx on the macports-guide branch: > > https://github.com/raimue/docbookrx/tree/macports-guide I fixed another problem with literals as `startupitem.*` was not interpreted as expected by AsciiDoctor and has to be written as `+startupitem.*+`: https://github.com/asciidoctor/asciidoctor/issues/1045 This style is now applied to all string literals by my patched docbookrx. The alternative would be to use only backticks in the conversion and fix broken occurrences by hand afterwards. I opted for the safe variant, although the syntax is not as lean as it could be. It has been almost two years... I would like to suggest we finally decide on a flag day on which I will do a final conversion of the DocBook to AsciiDoc and after that only the AsciiDoc version is kept in the repository. All remaining issues can then be worked on in the AsciiDoc files. Please test out the conversion from AsciiDoc to HTML and compare the result with the previous DocBook version: make guide-fromadoc && open guide/html/adoc/index.html The README.md file documents known issues and things that will need manual work after the final conversion. Feel free to add anything else you can spot: https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md If we are still not ready to make the switch, I would like to give up this experiment and delete all *.adoc files from the repository as the current state seems to be rather confusing for contributors. Rainer
Re: Migrating the guide to AsciiDoc
On 2018-04-22 09:29, Mojca Miklavec 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, but there are still some issues with conversion that > will have to be addressed either by fixing docbookrx itself or > manually. I fixed some of the issues by slightly modifying the XML. None of these should change the output produced by DocBook, but help docbookrx to understand the XML. I started to document the issues with the conversion in the README. This is not exhaustive, please add more things to this list if you spot them. https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md On one hand, some issues can only be fixed manually once we are sure we are not going to run docbookrx again. On the other hand, I noticed that it would be easier to fix other issues in docbookrx instead of post-processing the *.adoc files. However, some of the issues require tweaks to docbookrx that are specific to the MacPorts guide, as they depend on assumptions how certain elements are used. I pushed some commits with such changes that are specific to the MacPorts guide to my fork of docbookrx on the macports-guide branch: https://github.com/raimue/docbookrx/tree/macports-guide Should I move this repository to the MacPorts organization on GitHub for collaboration? This would only be temporary until we are finished with the conversion. Rainer
Re: Installing nokogiri with --use-system-libraries (was: Re: Migrating the guide to AsciiDoc)
On Apr 23, 2018, at 6:23 PM, Rainer Müller wrote: > $ sudo gem2.5 install nokogiri -- --use-system-libraries > … > pkg-config could not be used to find libxml-2.0 > … > "pkg-config --exists libxml-2.0" > dyld: Symbol not found: __cg_jpeg_resync_to_restart > Referenced from: > /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO > Expected in: /opt/local/lib/libJPEG.dylib > in /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO > package configuration for libxml-2.0 is not found > > This pkg-config command works fine outside of 'gem install’. Okay, try installing the ruby gem pkg-config version 1.1: $ sudo port select —set ruby ruby23 Selecting 'ruby23' for 'ruby' succeeded. 'ruby23' is now active. $ sudo gem install nokogiri-1.8.2.gem -- --use-system-libraries Building native extensions with: '--use-system-libraries' This could take a while... ERROR: Error installing nokogiri-1.8.2.gem: ERROR: Failed to build gem native extension. current directory: /opt/lib/ruby2.3/gems/2.3.0/gems/nokogiri-1.8.2/ext/nokogiri /opt/bin/ruby2.3 -r ./siteconf20180424-30290-tretof.rb extconf.rb --use-system-libraries … $ sudo gem install pkg-config --version 1.1 Fetching: pkg-config-1.1.0.gem (100%) Successfully installed pkg-config-1.1.0 Parsing documentation for pkg-config-1.1.0 Installing ri documentation for pkg-config-1.1.0 Done installing documentation for pkg-config after 0 seconds 1 gem installed $ sudo gem install nokogiri-1.8.2.gem -- --use-system-libraries Building native extensions with: '--use-system-libraries' This could take a while... Successfully installed nokogiri-1.8.2 Parsing documentation for nokogiri-1.8.2 Installing ri documentation for nokogiri-1.8.2 Done installing documentation for nokogiri after 23 seconds 1 gem installed $ > The crash report in Console.log shows that the invocation of pkg-config > included the environment variable: DYLD_LIBRARY_PATH=.:/opt/local/lib Yes, I see that even after installing pkg-config gem, but nokogiri install proceeds nonetheless.
Re: Installing nokogiri with --use-system-libraries (was: Re: Migrating the guide to AsciiDoc)
Hi,
On 23 April 2018 at 17:42, Rainer Müller wrote:
>
> Ruby and gems are really strange...
>
> Apparently, installing nokogiri with bundle fails
Wasn't it you who said that we don't need a port for it as it's just a
one-time conversion? :)
(I'm honestly not sure who said that.)
Looking at how elegant the asciidoctor port is ... I still believe we
should make a port for docbookrx.
(I guess someone first needs to document how to use a ruby portgroup,
so we need to get the conversion to asciidoc done first, right? :) :)
:)
> Here is a way to get it working:
>
> $ git clone https://github.com/asciidoctor/docbookrx
> $ cd docbookrx
> $ sudo port install rb23-bundler
> $ bundle-2.3 config --local build.nokogiri --use-system-libraries
> --with-xml2-dir=/opt/local --with-xml2-include=/opt/local/include/libxml2
> --with-xslt-dir=/opt/local --with-zlib-dir=/opt/local
> --with-exslt-dir=/opt/local --without-pkg-config
> $ bundle-2.3 install --path=.bundle/gems
Installing gems is a genuinely error-prone process on Mac, you can
find lots and lots of reports of broken behaviour and they are not
always responsive, sometimes deleting comments from tickets etc.
One example (which eventually got fixed, but there are a number of those):
https://github.com/sparklemotion/nokogiri/issues/1423
(I would have linked to another ticket, but my comments were boldly deleted.)
I was initially following this procedure:
https://gorails.com/setup/osx/10.13-high-sierra
basically
sudo port install rbenv ruby-build
(which should be up to date) and then installed bundler with rbenv.
For once, it magically worked and I was surprised since I've been
fighting with issues for years (on admittedly an older OS).
I have huge philosophical problems with this line:
--use-system-libraries --with-xml2-dir=/opt/local
--with-xml2-include=/opt/local/include/libxml2
--with-xslt-dir=/opt/local --with-zlib-dir=/opt/local
--with-exslt-dir=/opt/local
because this will lead to broken software as soon as one updates some
libraries under MacPorts. (Does HomeBrew ever delete old versions or
do their old versions of libraries remain installed forever until the
user removes them?)
I did not use any of those workarounds this time for once (I didn't
use external libraries).
You'll get an impression about the quality of the build system by
reading this (copy-pasted at the bottom) as "reference installation
instructions":
http://installrails.com/steps/install_rails
> Then go to the guide/xml/ directory of macports-guide:
>
> $ BUNDLE_GEMFILE=~/src/docbookrx/Gemfile bundle-2.3 exec docbookrx guide.xml
> $ mv *.adoc ../adoc/
I eventually managed to use
~/app/docbookrx/bin/docbookrx guide.xml
but I also didn't manage to make docbookrx a simple executable that I
could put or symlink into PATH.
On 24 April 2018 at 00:23, Rainer Müller wrote:
> On 2018-04-23 20:35, Andrew Moore wrote:
>> You might try:
>>
>> $ sudo gem update —system
>>
>> which should install the latest version of bundler (you really want that),
>> and go from there.
>> In the particular case of nokogiri, you might also try running `gem install
>> nokogiri` as user root.
>
> I am very cautious about running third-party package managers as root
> and let them write to ${prefix}. That is supposed to be managed by
> MacPorts and no other package manager should update files.
B no!!!
Why "sudo gem"? This sounds like a terrible idea. You should
absolutely install gems locally, not as sudo, and in particular not
under /opt/local.
Mojca
PS: Quotation from http://installrails.com/steps/install_rails:
If Rails cannot install, check the failure message. if it contains:
-
libxml2 is missing. Please locate mkmf.log to investigate how it
is failing.
-
and you are using OS X 10.10 or later, then run:
brew install libxml2
env ARCHFLAGS="-arch x86_64" gem install nokogiri:1.6.4.1 --
--use-system-libraries --with-xml=/usr/local/Cellar/libxml2/
to install libxml2 and nokogiri and rerun the rails instalation.
Else, try running the code below and then restarting your computer:
brew install apple-gcc42
Re: Installing nokogiri with --use-system-libraries (was: Re: Migrating the guide to AsciiDoc)
On Apr 23, 2018, at 6:23 PM, Rainer Müller wrote:
>
> On 2018-04-23 20:35, Andrew Moore wrote:
>> You might try:
>>
>> $ sudo gem update —system
>>
>> which should install the latest version of bundler (you really want that),
>> and go from there.
>> In the particular case of nokogiri, you might also try running `gem install
>> nokogiri` as user root.
>
> I am very cautious about running third-party package managers as root
> and let them write to ${prefix}. That is supposed to be managed by
> MacPorts and no other package manager should update files.
>
> If this overwrites any file provided by the ruby port, just running
> a deactivate/activate cycle will bring back the old version. Or an
> inconsistent state, if it also wrote new files to keep the version
> information.
>
> If there is ever going to be a rb23-nokogiri port, I expect this to
> cause conflicts later with files not known to MacPorts.
>
> When I uninstall the ruby port, this might leave traces behind
> in ${prefix} that can be cleaned up, but I would not be aware of that.
>
> nokogiri uses vendored versions of zlib/libxml2/libxslt and other
> dependencies by default. I already have them installed in ${prefix}
> and I do not want to build them again from source, therefore I used
> --use-system-libraries (as the README of docbookrx suggested).
>
> I even dared to give this a try as root (again, not recommended),
> but this also fails in the same way:
>
> $ sudo gem2.5 install nokogiri -- --use-system-libraries
> ...
> pkg-config could not be used to find libxml-2.0
> ...
>
> From .../mkmf.log:
>
> "pkg-config --exists libxml-2.0"
> dyld: Symbol not found: __cg_jpeg_resync_to_restart
> Referenced from:
> /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
> Expected in: /opt/local/lib/libJPEG.dylib
> in /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
> package configuration for libxml-2.0 is not found
>
> This pkg-config command works fine outside of 'gem install'.
>
> The crash report in Console.log shows that the invocation of pkg-config
> included the environment variable: DYLD_LIBRARY_PATH=.:/opt/local/lib
I do remember having to run as root user to get nokogiri to install at one time.
In particular, running as `sudo` was insufficient. I’m guessing that it was a
sandboxing
issue, but don’t recall the details, nor even the version of ruby involved.
That shouldn’t be
necessary today, though Nokogiri has been problematic to install at times over
the years.
I'll start right now trying to hunt the problem down, with a vanilla Install
of MacPorts on
a macOS 10.12 system and MacPorts ruby 2.3.
I’ll just mention while on topic that ruby is developed on Linux, so macOS
support can lag.
For instance, the current version of ruby-ffi works fine on *BSD, but not
macOS, where I have
to go back to an earlier version (1.9.21).
-AM
Installing nokogiri with --use-system-libraries (was: Re: Migrating the guide to AsciiDoc)
On 2018-04-23 20:35, Andrew Moore wrote:
> You might try:
>
> $ sudo gem update —system
>
> which should install the latest version of bundler (you really want that),
> and go from there.
> In the particular case of nokogiri, you might also try running `gem install
> nokogiri` as user root.
I am very cautious about running third-party package managers as root
and let them write to ${prefix}. That is supposed to be managed by
MacPorts and no other package manager should update files.
If this overwrites any file provided by the ruby port, just running
a deactivate/activate cycle will bring back the old version. Or an
inconsistent state, if it also wrote new files to keep the version
information.
If there is ever going to be a rb23-nokogiri port, I expect this to
cause conflicts later with files not known to MacPorts.
When I uninstall the ruby port, this might leave traces behind
in ${prefix} that can be cleaned up, but I would not be aware of that.
nokogiri uses vendored versions of zlib/libxml2/libxslt and other
dependencies by default. I already have them installed in ${prefix}
and I do not want to build them again from source, therefore I used
--use-system-libraries (as the README of docbookrx suggested).
I even dared to give this a try as root (again, not recommended),
but this also fails in the same way:
$ sudo gem2.5 install nokogiri -- --use-system-libraries
...
pkg-config could not be used to find libxml-2.0
...
>From .../mkmf.log:
"pkg-config --exists libxml-2.0"
dyld: Symbol not found: __cg_jpeg_resync_to_restart
Referenced from:
/System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
Expected in: /opt/local/lib/libJPEG.dylib
in /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
package configuration for libxml-2.0 is not found
This pkg-config command works fine outside of 'gem install'.
The crash report in Console.log shows that the invocation of pkg-config
included the environment variable: DYLD_LIBRARY_PATH=.:/opt/local/lib
Rainer
Re: MP manpages (was: Migrating the guide to AsciiDoc)
On Apr 23, 2018, at 3:46 PM, Jan Stary wrote: > > On Apr 23 16:26:13, rai...@macports.org wrote: >> On 2018-04-23 14:27, Jan Stary wrote: These quirks are added by DocBook XSLT and are apparently required to make the output compatible. If you disagree with that, talk to DocBook why they added them. >>> >>> You don't care that a 2008 workaround to a Debian bug >>> is included in every manpage of a MacPorts package system? >>> Or a 2009 workaround to a Solaris bug in GNU roff? >>> Don't you find it a prime example of clutter >>> that simply does not belong there? >> >> No, I really do not care about these workarounds. Why should I care >> about workarounds in intermediate formats? >> I do not see anything of this in my terminal. > > The asciidoc is what you don't see on you terminal. > The resulting man(7) page is what you see, rendered > by either groff (typically) or mandoc. > >> Again, this is added to every man page produced by DocBook and not >> specific to the man pages generated for MacPorts. We are not maintaining >> the XSLT stylesheets that produce this output. If you think these >> workarounds are not necessary, the DocBook project is the right address >> for complaints. > > I have no desire to "fix docbook", overengineered beyond absurdity. > My point is why do you want to use something like docbook > to produce the manpages? Jan, For what it’s worth, I like mdoc(7) and use it for my utilities - I even wrote one for the Apple's afconvert(1) utility (see attachment) - but for anything intended for distribution, the documentation gets rewritten in at least one other format, e.g., texinfo and/or markdown. There is no universal documentation format, e.g., ISO 8000 companies have their own problem. > All of OpenBSD, FreeBSD and NetBSD, in fact. And MacOS of course. > (I love how you try to make it sound as something negligible. > Remember how everyone except some BSD projects was using ssh.com > before OpenSSH was started in some BSD project?) Actually, if you download FreeBSD project documentation, e.g., https://github.com/freebsd/freebsd-doc, you’ll find that it’s written in DocBook. Again, for what it’s worth, while I’m not willing to maintain MacPorts mdoc(7) pages, I am willing to explore improving conversion from asciidoc to mdoc, because for project-wide documentation asciidoc seems like a reasonable choice. -AM afconvert.1 Description: Binary data
Re: MP manpages (was: Migrating the guide to AsciiDoc)
On Apr 23, 2018, at 14:46, Jan Stary wrote: Man, you sure love to argue about stuff. > The asciidoc is what you don't see on you terminal. > The resulting man(7) page is what you see, rendered > by either groff (typically) or mandoc. Asciidoc is what we see in an editor when we edit the manual. The output of groff is what we see in the Terminal. All the intermediate stuff isn't particularly interesting to me as long as the input is easy enough to write and the output is legible. >> Again, this is added to every man page produced by DocBook and not >> specific to the man pages generated for MacPorts. We are not maintaining >> the XSLT stylesheets that produce this output. If you think these >> workarounds are not necessary, the DocBook project is the right address >> for complaints. > > I have no desire to "fix docbook", overengineered beyond absurdity. > My point is why do you want to use something like docbook > to produce the manpages? As Rainer already explained: > On Apr 23, 2018, at 06:17, Rainer Müller wrote: > >> That is correct, DocBook XML is used because AsciiDoc has no native >> backend to produce man pages. >> >> However, AsciiDoctor has a native backend for man pages [1], which does >> not require the additional step through DocBook XML. If you, or anyone >> else, wants to look into switching the man page generation in base from >> AsciiDoc to AsciiDoctor, that would be appreciated. >>> How did you write the mdoc(7) manpages then? >> >> Those had been written before I even joined the project. Apparently >> someone wrote the original man pages, then left the project and no >> longer contributed. Nobody updated the man pages because they were >> written in a format nobody wanted to learn. > > Are you sure _that_ was the reason? It's pretty damn trivial to > update an _existing_ mdoc(7) manpage (such as: add an option, etc). Ok, then what was the reason, since you don't believe us when we tell you what we think it was? >> Therefore the plan came up >> to replace that format with something else that is easier to pick up for >> new contributors. > > Honest question: how much did people start contributing documentation, > after the switch from mdoc(7) to asciidoc? I don't recall seeing a lot of substantial changes to the asciidoc after the conversion. But, the conversion included a complete modern rewrite of the manpages, such that additional contributions weren't immediately necessary. I think if we had not allowed the manpages to be converted to asciidoc, the person who did the rewrite would not have wanted to do so. >> Although there was already some work to use DocBook XML for the man >> pages, I proposed to use AsciiDoc in the NewHelpSystem. This format was >> already used by other projects to write man pages. Just to name popular >> examples, git and mercurial still use it. I do not think that the HTML >> version of their man pages is missing semantics. I do not think that our >> HTML version [1] is missing semantics, either. > > What? > > (> [1] https://man.macports.org/port-diagnose.1.html > has almost no content; let's take port.1.html as an example:) > > port > [-bcdfknNopqRstuvy] [-D > portdir] [-F cmdfile] > [action] [actionflags] > [[portname | pseudo-portname > | port-expressions | port-url]] > [[@version] [+/-variant …] … > [option=value …]] > > There is _no_ semantics in here. Or what denotes an option here? > Or its (optional) argument? Nothing. This is purely presentational: > "put this in bold, type a bracket here". Does that matter? >> Back then, I did not even know there was a difference between man(7) and >> mdoc(7). And even today, neither looks like a syntax new contributors >> without previous knowledge want to write in my opinion. > > I do. I am willing to write it. > Please just say you simply don't want it. I think that, having spent a very long time on rewriting the manpages in asciidoc--a process which is not yet 100% complete--we're now unclear on why we would want to convert to yet another different format now.
MP manpages (was: Migrating the guide to AsciiDoc)
On Apr 23 16:26:13, rai...@macports.org wrote:
> On 2018-04-23 14:27, Jan Stary wrote:
> >> These quirks are added by DocBook XSLT and are apparently required to
> >> make the output compatible. If you disagree with that, talk to DocBook
> >> why they added them.
> >
> > You don't care that a 2008 workaround to a Debian bug
> > is included in every manpage of a MacPorts package system?
> > Or a 2009 workaround to a Solaris bug in GNU roff?
> > Don't you find it a prime example of clutter
> > that simply does not belong there?
>
> No, I really do not care about these workarounds. Why should I care
> about workarounds in intermediate formats?
> I do not see anything of this in my terminal.
The asciidoc is what you don't see on you terminal.
The resulting man(7) page is what you see, rendered
by either groff (typically) or mandoc.
> Again, this is added to every man page produced by DocBook and not
> specific to the man pages generated for MacPorts. We are not maintaining
> the XSLT stylesheets that produce this output. If you think these
> workarounds are not necessary, the DocBook project is the right address
> for complaints.
I have no desire to "fix docbook", overengineered beyond absurdity.
My point is why do you want to use something like docbook
to produce the manpages?
> 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.
> >>
> >> We moved away from mdoc(7) with the NewHelpSystem [1]. It took us about
> >> five years to write all man pages, including conversion of the old man
> >> pages.
> >
> > $ cd /opt/mports/macports-base/doc
> > $ wc -l *.txt *.1 *.5 *.7
> >
> > That would make it about nine lines per day.>
> > BTW, was it mdoc(7) or man(7)?
>
> mdoc(7).
>
> You seem to count both the input and the output files. Also, some of the
> old files, such as portfile.7 and porthier.7, still have not been
> converted. The real progress was even slower than that.
>
> > How did you write the mdoc(7) manpages then?
>
> Those had been written before I even joined the project. Apparently
> someone wrote the original man pages, then left the project and no
> longer contributed. Nobody updated the man pages because they were
> written in a format nobody wanted to learn.
Are you sure _that_ was the reason? It's pretty damn trivial to
update an _existing_ mdoc(7) manpage (such as: add an option, etc).
> Therefore the plan came up
> to replace that format with something else that is easier to pick up for
> new contributors.
Honest question: how much did people start contributing documentation,
after the switch from mdoc(7) to asciidoc?
> Although there was already some work to use DocBook XML for the man
> pages, I proposed to use AsciiDoc in the NewHelpSystem. This format was
> already used by other projects to write man pages. Just to name popular
> examples, git and mercurial still use it. I do not think that the HTML
> version of their man pages is missing semantics. I do not think that our
> HTML version [1] is missing semantics, either.
What?
(> [1] https://man.macports.org/port-diagnose.1.html
has almost no content; let's take port.1.html as an example:)
port
[-bcdfknNopqRstuvy] [-D
portdir] [-F cmdfile]
[action] [actionflags]
[[portname | pseudo-portname
| port-expressions | port-url]]
[[@version] [+/-variant …] …
[option=value …]]
There is _no_ semantics in here. Or what denotes an option here?
Or its (optional) argument? Nothing. This is purely presentational:
"put this in bold, type a bracket here".
> Back then, I did not even know there was a difference between man(7) and
> mdoc(7). And even today, neither looks like a syntax new contributors
> without previous knowledge want to write in my opinion.
I do. I am willing to write it.
Please just say you simply don't want it.
> I see you are strongly attached to mdoc(7), but take a look around:
> except some *BSD projects nobody uses mdoc(7) to write man pages.
All of OpenBSD, FreeBSD and NetBSD, in fact. And MacOS of course.
(I love how you try to make it sound as something negligible.
Remember how everyone except some BSD projects was using ssh.com
before OpenSSH was started in some BSD project?)
$ vi `man -w ls`
> Most
> projects use lightweight markup languages such as AsciiDoc, Markdown, or
> restructuredText, or even pod2man for this task.
No, most project don't. and even if they did,
is that a reason to do it too?
> $ find /opt/local/share/man | wc -l
>15591
> $ find /opt/local/share/man -exec zgrep -l '^.Dt' {} + | wc -l
> 588
Well, that differs by user of course:
$ find /opt/local/share/man -type f | wc -l
3493
$ find /opt/local/share/man -type f | xargs -n1 zgrep ^.TH | wc -l
2574
$ find /opt/local/share/man -type f | xargs -n1 zgrep ^.Dt | wc -l
537
Also, this just greps for man(7) manpages;
that does not mean they are produced by asciidoc
Re: Migrating the guide to AsciiDoc
On Apr 23, 2018, at 11:42 AM, Rainer Müller wrote: > > On 2018-04-22 09:29, Mojca Miklavec wrote: >> Hi, >> >> 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, but there are still some issues with conversion that >> will have to be addressed either by fixing docbookrx itself or >> manually. > > Ruby and gems are really strange… I had the impression that MacPorts rb-* gems were completely abandoned. I haven't run ruby2.3 for a while, but have no problem with either ruby2.5 or ruby2.6dev. You might try: $ sudo gem update —system which should install the latest version of bundler (you really want that), and go from there. In the particular case of nokogiri, you might also try running `gem install nokogiri` as user root. $ ruby --version ruby 2.6.0dev (2018-04-23) [x86_64-darwin17] $ bundle --version Bundler version 1.16.1 $ git clone https://github.com/asciidoctor/docbookrx … $ cd docbookrx $ bundle Fetching gem metadata from https://rubygems.org/.. Resolving dependencies... Fetching rake 10.4.2 Installing rake 10.4.2 Using bundler 1.16.1 Using diff-lcs 1.3 Using mini_portile2 2.3.0 Using nokogiri 1.8.2 Using docbookrx 1.0.0.dev from source at `.` Fetching rspec-support 3.4.1 Installing rspec-support 3.4.1 Fetching rspec-core 3.4.4 Installing rspec-core 3.4.4 Fetching rspec-expectations 3.4.0 Installing rspec-expectations 3.4.0 Fetching rspec-mocks 3.4.1 Installing rspec-mocks 3.4.1 Fetching rspec 3.4.0 Installing rspec 3.4.0 Bundle complete! 3 Gemfile dependencies, 11 gems now installed. Use `bundle info [gemname]` to see where a bundled gem is installed. $ rake build docbookrx 1.0.0.dev built to pkg/docbookrx-1.0.0.dev.gem. $ sudo gem install pkg/docbookrx-1.0.0.dev.gem Successfully installed docbookrx-1.0.0.dev Parsing documentation for docbookrx-1.0.0.dev Installing ri documentation for docbookrx-1.0.0.dev Done installing documentation for docbookrx after 2 seconds 1 gem installed $
Re: Migrating the guide to AsciiDoc
On 2018-04-22 09:29, Mojca Miklavec wrote: > Hi, > > 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, but there are still some issues with conversion that > will have to be addressed either by fixing docbookrx itself or > manually. Ruby and gems are really strange... Apparently, installing nokogiri with bundle fails because it tries to execute pkg-config with DYLD_LIBRARY_PATH set, for whatever reason. This leads to crashes as it draws in incompatible versions of libjpeg. I was not even able to determine where this DYLD_LIBRARY_PATH in the environment is coming from. Here is a way to get it working: $ git clone https://github.com/asciidoctor/docbookrx $ cd docbookrx $ sudo port install rb23-bundler $ bundle-2.3 config --local build.nokogiri --use-system-libraries --with-xml2-dir=/opt/local --with-xml2-include=/opt/local/include/libxml2 --with-xslt-dir=/opt/local --with-zlib-dir=/opt/local --with-exslt-dir=/opt/local --without-pkg-config $ bundle-2.3 install --path=.bundle/gems Then go to the guide/xml/ directory of macports-guide: $ BUNDLE_GEMFILE=~/src/docbookrx/Gemfile bundle-2.3 exec docbookrx guide.xml $ mv *.adoc ../adoc/ Rainer
Re: Migrating the guide to AsciiDoc
On 2018-04-23 14:27, Jan Stary wrote:
>> These quirks are added by DocBook XSLT and are apparently required to
>> make the output compatible. If you disagree with that, talk to DocBook
>> why they added them.
>
> You don't care that a 2008 workaround to a Debian bug
> is included in every manpage of a MacPorts package system?
> Or a 2009 workaround to a Solaris bug in GNU roff?
> Don't you find it a prime example of clutter
> that simply does not belong there?
No, I really do not care about these workarounds. Why should I care
about workarounds in intermediate formats? I do not see anything of this
in my terminal.
Again, this is added to every man page produced by DocBook and not
specific to the man pages generated for MacPorts. We are not maintaining
the XSLT stylesheets that produce this output. If you think these
workarounds are not necessary, the DocBook project is the right address
for complaints.
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.
>>
>> We moved away from mdoc(7) with the NewHelpSystem [1]. It took us about
>> five years to write all man pages, including conversion of the old man
>> pages.
>
> $ cd /opt/mports/macports-base/doc
> $ wc -l *.txt *.1 *.5 *.7
>
> That would make it about nine lines per day.>
> BTW, was it mdoc(7) or man(7)?
mdoc(7).
You seem to count both the input and the output files. Also, some of the
old files, such as portfile.7 and porthier.7, still have not been
converted. The real progress was even slower than that.
> How did you write the mdoc(7) manpages then?
Those had been written before I even joined the project. Apparently
someone wrote the original man pages, then left the project and no
longer contributed. Nobody updated the man pages because they were
written in a format nobody wanted to learn. Therefore the plan came up
to replace that format with something else that is easier to pick up for
new contributors.
Although there was already some work to use DocBook XML for the man
pages, I proposed to use AsciiDoc in the NewHelpSystem. This format was
already used by other projects to write man pages. Just to name popular
examples, git and mercurial still use it. I do not think that the HTML
version of their man pages is missing semantics. I do not think that our
HTML version [1] is missing semantics, either.
Back then, I did not even know there was a difference between man(7) and
mdoc(7). And even today, neither looks like a syntax new contributors
without previous knowledge want to write in my opinion.
I see you are strongly attached to mdoc(7), but take a look around:
except some *BSD projects nobody uses mdoc(7) to write man pages. Most
projects use lightweight markup languages such as AsciiDoc, Markdown, or
restructuredText, or even pod2man for this task.
$ find /opt/local/share/man | wc -l
15591
$ find /opt/local/share/man -exec zgrep -l '^.Dt' {} + | wc -l
588
Rainer
[1] https://man.macports.org/port-diagnose.1.html
Re: Migrating the guide to AsciiDoc
On Apr 23 13:17:10, rai...@macports.org wrote: > On 2018-04-23 10:12, Jan Stary wrote: > >>> 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. > > > > > > https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html > > I do not care about the raw input, (apparently) > I read man pages in rendered form with man(1). I thought we are talking about _producing_ the manpages. That _is_ the raw input (in whichever markup language). > These quirks are added by DocBook XSLT and are apparently required to > make the output compatible. If you disagree with that, talk to DocBook > why they added them. You don't care that a 2008 workaround to a Debian bug is included in every manpage of a MacPorts package system? Or a 2009 workaround to a Solaris bug in GNU roff? Don't you find it a prime example of clutter that simply does not belong there? > >> 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. > > We moved away from mdoc(7) with the NewHelpSystem [1]. It took us about > five years to write all man pages, including conversion of the old man > pages. $ cd /opt/mports/macports-base/doc $ wc -l *.txt *.1 *.5 *.7 That would make it about nine lines per day. BTW, was it mdoc(7) or man(7)? > >> .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 ksamm...@macports.org > > I really cannot see the benefits of this. To me, writing this by hand > would be even more terrible than writing XML. > I have no idea what any of > these two-character commands mean. How did you write the mdoc(7) manpages then? > This syntax is far from being intuitive. Nm name Op Fl optional flag Ar argument Sh section header Seriously, it takes about 15 minutes to get going. http://mandoc.bsd.lv/man/mdoc.7.html The main point is that mdoc(7) allows for constructs like .Op Fl f Ar arg meaning there is an optional 'f' flag which takes an 'arg' argument as opposed to switch to italics, type a bracket, a dash, "f", then switch to boldface and type "arg" in the physical roff markup of man(7). Similarly for other constructs like cross-references, filenames, author emails, env variables, etc. > Yes, it seems to be possible to encode more semantics than with > AsciiDoc. But do we really need that in a man page? Yes; you can _search_ by those semantics then, such as by a filename mentioned in FILES; or by AUTHORS; you get html manpages for free and can do things like http://man.openbsd.org/ls#d i.e. link to individual options and sections. > But do we really need that in a man page? Do we need 2008 workarounds to Debian bugs in a manpage? > At least for terminal output, almost everything of that > is lost with rendering anyway. No it's not. And terminal output is not the only: you get html, pdf, ps, even mandoc from it, without docbook; mdoc(7) is a language that has been in UNIX for decades and is very well supported everywhere. > If you really care that much about the non-rendered file on disk, > I would recommend to rewrite the DocBook XSLT to use the mdoc(7) format > or contribute a native backend for it to AsciiDoctor. I'm not touching DocBook, obviously. My main motivation here is to get rid of it entirely. And asciidoc has no way of even expressing the semantics. Again, I am willing to do the work. Please let me know if there is no interest. Jan
Re: Migrating the guide to AsciiDoc
On 2018-04-23 10:42, Jan Stary wrote: > Also, having manpages written in asciidoc means we need > the abominable docbook to actually produce the man(7) pages, right? > At least that's what it says at the end of install: > > * Warning: Using pre-generated man pages only. > * asciidoc, xsltproc (port libxslt) and docbook-xsl are required > to generate man pages from source. That is correct, DocBook XML is used because AsciiDoc has no native backend to produce man pages. However, AsciiDoctor has a native backend for man pages [1], which does not require the additional step through DocBook XML. If you, or anyone else, wants to look into switching the man page generation in base from AsciiDoc to AsciiDoctor, that would be appreciated. Rainer [1] https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/converter/manpage.rb
Re: Migrating the guide to AsciiDoc
On 2018-04-23 10:12, Jan Stary wrote: >>> 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. > > > https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html I do not care about the raw input, I read man pages in rendered form with man(1). These quirks are added by DocBook XSLT and are apparently required to make the output compatible. If you disagree with that, talk to DocBook why they added them. >> 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. We moved away from mdoc(7) with the NewHelpSystem [1]. It took us about five years to write all man pages, including conversion of the old man pages. >> .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 ksamm...@macports.org I really cannot see the benefits of this. To me, writing this by hand would be even more terrible than writing XML. I have no idea what any of these two-character commands mean. This syntax is far from being intuitive. Yes, it seems to be possible to encode more semantics than with AsciiDoc. But do we really need that in a man page? At least for terminal output, almost everything of that is lost with rendering anyway. If you really care that much about the non-rendered file on disk, I would recommend to rewrite the DocBook XSLT to use the mdoc(7) format or contribute a native backend for it to AsciiDoctor. Rainer [1] https://trac.macports.org/wiki/NewHelpSystem
Re: Migrating the guide to AsciiDoc
On Apr 23 10:09:06, mo...@macports.org wrote: > On 23 April 2018 at 09:42, Jan Stary wrote: > > On Apr 22 09:29:53, mo...@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 > > No. > > > 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? > > Yes. The guide should be converted to HTML (and ideally also PDF). Can the conversion to PDF happen without docbook? (i.e. can asciidoc(tor|*) produce pdf itself?) > The fact that GitHub can interpret the format is just a bonus that > might also help developers when editing the page, but it's not meant > to be the final product. > > 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?) > > Yes, one can directly generate html. But we need to figure out how to > do page splitting etc. This is why Rainer suggested to temporarily go > through docbook again. This is not absolutely set in stone though, if > someone polishes the process to sufficient details to allow > straightforwand conversion, we can use that one. > > (I believe the main reason why going through docbook was considered > was because none of us took the time to figure out how to make a > multi-page html from asciidoc directly.) Apparently, it still cannot do multi-page output: https://github.com/asciidoctor/asciidoctor/issues/626 https://github.com/openSUSE/asciidoctor/issues/9 Which means this does not get rid of docbook: it adds to the top of it (or the bottom of it). Jan
Re: Migrating the guide to AsciiDoc
On Apr 23 10:12:06, h...@stare.cz wrote: > > > 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. > > https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html > Also, having manpages written in asciidoc means we need the abominable docbook to actually produce the man(7) pages, right? At least that's what it says at the end of install: * Warning: Using pre-generated man pages only. * asciidoc, xsltproc (port libxslt) and docbook-xsl are required to generate man pages from source. Jan > > 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 ksamm...@macports.org
Re: Migrating the guide to AsciiDoc
> > 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. https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html > 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 ksamm...@macports.org
Re: Migrating the guide to AsciiDoc
On 23 April 2018 at 09:42, Jan Stary wrote: > On Apr 22 09:29:53, mo...@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 No. > 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? Yes. The guide should be converted to HTML (and ideally also PDF). The fact that GitHub can interpret the format is just a bonus that might also help developers when editing the page, but it's not meant to be the final product. > On Apr 22 11:39:23, rai...@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? Neither of them, the conversion was done with docbookrx, the link is also on https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md so https://github.com/asciidoctor/docbookrx > 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?) Yes, one can directly generate html. But we need to figure out how to do page splitting etc. This is why Rainer suggested to temporarily go through docbook again. This is not absolutely set in stone though, if someone polishes the process to sufficient details to allow straightforwand conversion, we can use that one. (I believe the main reason why going through docbook was considered was because none of us took the time to figure out how to make a multi-page html from asciidoc directly.) Mojca
Re: Migrating the guide to AsciiDoc
On Apr 22 09:29:53, mo...@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, rai...@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 ksamm...@macports.org
Re: Migrating the guide to AsciiDoc
On 2018-04-22 09:44, Andrew Moore wrote: > Just to be clear, asciidoc is the format, but asciidoctor is the text > processor (a superset of python asciidoc). Is that correct? Yes. 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. We are already using the AsciiDoc format for our man pages, and that has proved to be a good choice, because the format is quite extensible (custom macros, includes, etc.). Rainer
Re: Migrating the guide to AsciiDoc
Just to be clear, asciidoc is the format, but asciidoctor is the text processor (a superset of python asciidoc). Is that correct? -AM > On Apr 22, 2018, at 3:29 AM, Mojca Miklavec wrote: > > Hi, > > 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, 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. > > Thank you, >Mojca
Migrating the guide to AsciiDoc
Hi, 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, 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. Thank you, Mojca
