Eric et al, Generally speaking, Lex and I keep a watch over AsciiDoc Python / asciidoc.org. I'm also in communication with Stuart. So I assure you that, even though it appears to be moving slow (as OSS sometimes does), nothing is splintering.
I can perhaps offer some insight that extends what Lex wrote. We have heard very LOUD and CLEAR that now's the time for moving on an AsciiDoc specification / standard and overhaul of asciidoc.org. There have been at least a half dozen such threads in about as many months. We're all aligned on this. You could say I'm painfully aware of the situation and plea. And I definitely grasp the problem. I am *days away* from submitting a proposal that outlines a new path forward. Given that doing anything of the sort requires a substantial volunteer effort on my part, it's something I'm taking my time to prepare for (and not taking lightly). What I ask is that the community remain patient for this proposal so we have something concrete to discuss. Given that AsciiDoc is 10+ years old, I think we can spare a few more days. there are already four dialects > Can you enumerate which dialects you think there are? (I have an idea, but I want to know your perspective). As Lex pointed out, Asciidoctor is the current reference implementation of AsciiDoc (based on usage and activity), not AsciiDoc Python. or we going to have another absent-father situation like John Gruber > vis-a-vis Markdown, with asciidoc fragmenting into a million dialects > I assure you this will not happen. Avoiding such a situation is at the forefront of my mind. Besides, the originator is not gone. He's just no longer active. And I am in contact with him. So there's a big difference. In the meantime, I'm all in favor of making updates to the website that alleviate short-term pain*. But ultimately, what Lex said about making asciidoc.org about the *language* and not the AsciiDoc Python implementation, is a vision I share. Best Regards, -Dan * The main reason the website has fallen out of date is because it uses an obscure site builder that no one can seem to run. This makes what should be a simple update be absurdly complex. If someone can figure out how to get Travis CI to build the website from scratch, then it would go a long way to making updates simpler. asciidoc's config-file interpretation rules can best be described as a > horrible mess that clearly grew by accretion rather than design. > That's why I choose not to implement that in Asciidoctor. It was unimportant to the language itself and was way too obscure to carry forward. We are better off with a proper extension API. On Thu, Jan 3, 2019 at 1:36 PM Eric Raymond <[email protected]> wrote: > On Thursday, January 3, 2019 at 10:33:03 AM UTC-5, Lex Trotman wrote: >> >> 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'm aware of that port. > > >> 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. >> > > OK, forked and cloned. > > >> 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'm all for separation of concerns. But the perfect should not be the > enemy of the good, and right now the website reads as though the latest > release is 2.6.9 and the site has not been updated in 5 years. That is > dismaying and dispiriting. It's going to discourage people from investing > in any implementation at all. It's a serious PR weakness. > > If I send you an MR to fix that bug, will you merge it? > > >> > 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. >> > > OK, I'll do an MR for that. > > >> > 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. >> > > Understood. But there needs to be one place where a user can go to see a > list of pointers to differences between the base version documented at > asciidoc.org and the variant implementations. Where does that belong if > not on asciidoc.org? > > >> > 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. >> > > Of course I don't *want* to be tied to a specific implementation, why > would you think a desire that idiotic is even plausible? I didn't have a > choice; asciidoctor threw away a feature I needed. I'd like to replace my > use of that feature with something portable, but right now it is difficult > to know what portable is because the information about inter-implementation > differences is scattered and difficult to find. Perhaps you are too close > to the problem to see this. > > > 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) >> > > Oh, good. It is a relief to me to know that the ice has been broken on > getting the Python 3 port into major distros. It makes me less worried > about the long- and medium-term future. > > >> > 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 :) >> > > Well, from what you say it *is* ready for prime time (which is more good > news) so I won't worry about that quite so much. > > But suppose, say, I proposed bringing to the Python 3 port the asciidoctor > feature that XML named &-references (in addition to the numeric & > references) are interpreted properly. Would that become a base-language > feature to be described at asciidoc.org? Would the Python 2 > implementation then become nonconforming? How are these things to be > decided? > > >> > 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. >> > > That's not a really useful answer. The useful answer would describe what > subset of configuration the different implementations *can* do in common, > then standardize that. For example, is there any good reason for > text-substitution definitions to have different formats or for the conf > files for them to live in different places between implementations? > > A related question is under what circumstances the development group is > willing to break backward compatibility in order to clean up the mess in > the Python implementation. That is a policy question about which don't yet > have a fixed opinion, but I do think it is a question that needs to be > decided for the sake of people who are serious long-term asciidoc users > (like myself). > > >> I guess you need to think what you actually need from an >> implementation, > > > My major concern is not any individual missing feature, it is the cloud of > vagueness around the overall future of asciidoc. I think maybe you are too > close to the project to see how alarming things look from the outside. > Consider: > > * The originator is gone. Who is running the show? Is there a BDFL, a > steering committee, or we going to have another absent-father situation > like John Gruber vis-a-vis Markdown, with asciidoc fragmenting into a > million dialects? *shudder* > > * Speaking of those million dialects, there are already four dialects. > And no standardization effort in sight. And no public evidence that the > developers of these dialects even grasp that's a problem. > > * The FAQ says to use .txt as a file extension, but it's behind the curve. > GitHub and GitLab have have standardize on .adoc; is anybody at the > implementations paying attention, or are they content to let the world move > on without them? > > * asciidoc.org looks like it hasn't been updated in five years. > > It really does not add up to a pretty picture. And this bothers me - I > like asciidoc and want to keep using it. > > Good steps to take, in my opinion: > > * Update the website > > * Form an actual steering and standards committee, > > * Announce that the Python 2 implementation will be end-of-lifed on date X > and receive no further updates, with users told to switch the the Python 3 > port. > > * Push Debian/Ubuntu to replace the Python 2 package with the Python 3 > one. (Because between Fedora and Ubuntu the minor distros will follow,) > > 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. >> > > Best boot up that standards committee now, then. > > Dammit, I guess I'm volunteering to be on it. As if I needed another time > sink in my life. > > > -- > 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. > -- Dan Allen | @mojavelinux | https://twitter.com/mojavelinux -- 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.
