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] > <javascript:>> 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.
