On Fri, 4 Jan 2019 at 00:36, Eric Raymond <[email protected]> wrote: > > asciidoc is my favorite document markup language. I'm writing a book in it > now: "The Programmer's Way: a guide to right mindset". I also rely on it as > the leade of the NTPsec project; our documentation and our website is all > built in asciidoc. > > Because I need this tool to work and to keep working,
Then you will be pleased that there is a Python 3 port in the asciidoc/asciidoc-py3 repository. Since Python 2 EOLs 1 Jan 2020, ie just under a year in the future, it is the Python 3 port thats needed to continue development of the Python implementation. > I've become concerned by what appears to be drift and fragmentation in the > community around it. > Rather than just complain, I'm willing to pitch in and help. I can offer > strong skills in Python and in writing or editing documentation. > > One area of concern I have is that asciidoc.org looks stale. I have 8.6.10 > installed, but the main asciidoc.org page is still written as though 8.6.9 is > the latest release. > > Who controls asciidoc.org? Is it updated from a public repository? Can I get > write access or make MRs to do updates on it? If I could get those > permissions I would write the release update myself. The current website is served from the gh-pages branch of the asciidoc/asciidoc repository where the pages are made from the relevant sources in master. So only the normal github pull request process is needed to change it. But the general plans (subject to available resources) of the Asciidoc community not just one implementation is that the "asciidoc.org" URL will not be about the Asciidoc Python 2 implementation, instead it will be about Asciidoc the language, not any specific implementation. At the moment the Python 3 port docs (which are almost identical I expect, it being a port) are not published, they should become the docs for that implementation and be available, but not as the whole site asciidoc.org. > > I have also recently learned that asciidoc is missing some book example > files, which I now actually have. I would be willing to take responsibility > for making sure those go up on the site and clearing the rights with Stuart > Rackham, but I'd need write access to do that. As I said above, just a pull request should suffice. > > There are now four competing implementations of asciidoc. I do not view this > as a bad thing, but I do think it is a problem that there is no one place > where users can go to learn how they differ functionally from each other. > I'd be willing to work on fixing this. Again, I would need write access to > asciidoc.org; I would also need a little cooperation from the implementation > maintainers - basically, stable pointers to their own difference lists. As I said above, Asciidoc.org is intended to become the language reference, each implementation would be expected to define the differences it has to that, and the extra facilities it has too. > > Given that Stuart Rackham has retired from development, I'm gathering that > base Python asciidoc should be considered end-of-lifed and there will be no > more releases. Does the official Python 3 port now test as equivalent to it? > I'm concerned about this because Python 2 is going to EOL in 2020 and I need > to plan on a longer timescale than that, especially with respect to NTPsec. See above, but do you actually want to tie yourself to a specific implementation? Asciidoctor is currently the most active implementation. > > It seems to me that right about now we ought to be declaring the Python 3 > port release 9.0.0 and telling the distros to replace the Python 2 port. Is > anyone in charge of this kind of decision? Are all the maintainers for the > variants on this list? Some distros have already done that (well at least Fedora) > > If there's some technical reason the Python 3 port is not ready for prime > time I am willing to pitch in and code. Its a volunteer open source project, nothing will happen to it unless people contribute, so assistance is always welcome. But some discussion of just what changes are to be coded could be useful :) > > There are also some language issues that concern me. > NTPsec is using base asciidoc because asciidoctor tossed out a particular > configuration-file feature that we needed. Thats always the risk of being tied to a specific implementation, due to differences in implementation languages, intended target users etc, each is likely to have its own configuration and extension features that will not be portable. > On the other hand, base asciidoc's config-file interpretation rules can best > be described as a horrible mess that clearly grew by accretion rather than > design. Yep. > There is clearly cleanup work to be done in this area, but I'm concerned that > attempting it will increase user pain unless the three live variants dob some > coordination so that the cleaned-up behavior is reasonably stable across > implementations. As I said above, thats very unlikely, the intention is to standardise Asciidoc the markup language, but trying to enforce specific configuration files on very differently structured implementations is unlikely to work. Asciidoc Python is a stream oriented converter, Asciidoctor is partly parsed to a tree and partly stream converter (with a goal to move more to a parsed tree IIUC) and an experimental implementation I am playing with is entirely parsed to a tree then that is manipulated and converted. I don't know about Asciidoctor, but I can't see how I would use any configuration that looks even vaguely like the Asciidoc Python config files, their contents just doesn't fit the implementation. > > Again, I'm not just here to bitch. This tool is important to me and I'm > willing to put in work to fix these problems. What else can I do to help? > I guess you need to think what you actually need from an implementation, if you have a specific configuration that you can't move from Asciidoc Python then its the Python 3 port you need to move to, its very young and either it works perfectly or nobody is testing it, because there are very few problem reports :) As I said above the intention is for the asciidoc.org site to be about the language itself, and the development of a specification, hopefully this year sometime. Cheers Lex > > > > > > -- > You received this message because you are subscribed to the Google Groups > "asciidoc" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at https://groups.google.com/group/asciidoc. > For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/asciidoc. For more options, visit https://groups.google.com/d/optout.
