Hi Dan, On 28 August 2014 18:00, Dan Allen <[email protected]> wrote: > I'm chiming in just to let you know that I'm listening. There's still much > to learn, especially from authors. I listen and learn as much as I talk > about AsciiDoc :) > > AsciiDoc continues to see great adoption (especially lately) because it has > a great & noble goal: to make documentation (particularly formal > documentation) more approachable and more efficient to write. My focus in > the last few years has been to accelerate this impact. > > I've heard from many writers, especially information architects and > companies maintaining large documentation projects, that AsciiDoc is good, > but it can be better. We are experimenting with the AsciiDoc syntax to make > it more approachable and more efficient to write. Software and documentation > cannot stand still (because the world doesn't stand still). We are doing > everything we can to maintain the spirit of AsciiDoc in Asciidoctor while > accommodating the needs of a changing world and integrating new ideas. It's > a careful balance we have to maintain & respect...though not always easy.
Indeed nobody can expect the world to stand still, so long as asciidoctor/asciidocgo/asciidocpython version 31415.0.0 still lets someone doing configure; make; make install on some project get their documentation generated from the asciidoc source. The current approach of maintaining backward compatibility (at least for some reasonable time) is good. But I do dislike the current effective removal of two line headers by making them signal old syntax, without even a deprecation period. I really *HATE* the one line syntax, having to *COUNT* f-ing equals all the time :( When I can just recognise two line titles. I don't care if the syntax is hard for the processor, thats its problem, I'm reading the stuff all the time as I'm writing and its a pain to count. [end rant] > > The request I've heard more than any other is to create a standard for > AsciiDoc. Time permitting, I have plans to initiate the standardization > process and contribute to it in whatever way I can (it's hard to know what > the future holds). The working title for the standard is "UniDoc", short for > a "universal documentation (shorthand) language" and to shake the > misconception that AsciiDoc doesn't handle Unicode. We may throw that title > away, but it's a useful code name for referring to the standard now. I'll be > sure to post any progress on this initiative here so everyone knows what's > going on. Right now, the ETA is ETA :) Yes, a standard is indeed becoming important as more implementations come into existance, the last thing that is needed is for asciidocgo to go :) a different way to asciidoctor or asciidocpy3. > > Lex wrote: >> >> The tools asciidoc and asciidoctor are just that, tools. Don't >> confuse them with the markup syntax. > > > Yes and no. Asciidoctor is introducing new syntax because, as I mentioned, > the world has new needs and AsciiDoc must evolve. However, I do believe that > this syntax can either be made to be part of the AsciiDoc / UniDoc standard > or described via an extension (traditionally called an AsciiDoc filter), so > that we never break away from the composition of the AsciiDoc syntax. The > purpose of the standard is to provide the roots of the language that allow > any number of implementations, interpretations and extensions...but always > reusable content separate from presentation! Absent a standard, the tools *are* the standard, each with its own (with the best of intentions) improvements, and yes thats exactly the wrong way to do it. Having a standard which is defined in an implementation agnostic form is the way forward. The only potential problem is to avoid the current docbook toolchain problem where common tailoring of the presentation is so tool specific that the user is locked into that tool once they have done it, but don't define the presentation mapping/theming/extensions so tightly that there is no freedom for the implementations to innovate (outside the content markup language of course). Having been involved in standardisation processes in the past, they are sadly slow and boooooring, that will be a very different challenge to do in an open manner. > > (We also need to have a formal grammar because that is a huge barrier to new > implementations. We will have a formal grammar. Documentation is too > important to be based on a language with no formal grammar). +1 > > Stéphane Gourichon wrote: >> >> Now I have chosen to stay with asciidoc but the reason is not obvious. >> Asciidoc has drawbacks but asciidoctor feels to walk a wrong way. > > > I'm curious what path you think we are taking that we shouldn't. We > certainly want to be on the right path. > > I want to emphasize that, although we are exploring direct AsciiDoc to > output formats, we are definitely not abandoning DocBook (in fact, we now > produce DocBook 5, something AsciiDoc Python still lacks!). I wholeheartedly > agree that DocBook is a great document interchange format. I just don't > think any human should be touching it (at least, not as part of content > authoring). +100000000000 (I'm XML allergic :) > > (I also think that the *way* DocBook is processed is completely insane. I am > not a believer in XSL. I've been down that road. I think it's a terrible > waste of engineering resources. However, my opinion really doesn't matter on > the subject. If it works for you, then by all means, I encourage you to use > what works for you. That's the great thing about separating content from > presentation. You are free to follow your own path when converting). The only real problem is that the high quality rendering paths are still proprietary, but that may change. > > Gour wrote: >> >> In the past I used LyX/LaTeX for quality typesetting, but now I believe >> I could simply use Asciidoc --> PDF when then desired quality does not >> have to be top-notch and use your toolchain when I want to do fine >> tuning of latex file. > > > Another option here is just print to PDF in the browser (e.g., Chrome or > Firefox). The default Asciidoctor stylesheet includes CSS that makes the > printed document look very professional. (Note that the default Asciidoctor > stylesheet can be used with AsciiDoc Python as well). Many companies, > including Red Hat, are abandoning the DocBook toolchain in favor of > "printing" the document PDF using WebKit (via wkhtmltopdf or phantomjs). > It's worth considering, especially for quick stuff. So that explains some of the crappy PDFs around :) These tools are not (yet) high quality rendering for page based outputs principally because they take a deviation via a flow based format (HTML). I would think it would be hard to make that path high quality since in the HTML you have lost the semantics that the Asciidoc content markup provided and which is important to guide the page based rendering. > > If you have any questions about the direction we're headed with Asciidoctor, > feel free to ask. I'm always listening! > Dan wrote: >One of my long term goals for Asciidoctor is to encourage a *new* >implementation of AsciiDoc in Python 3. AsciiDoc Python 2 has brought us a >loooooong way in the last decade. However, having spent a lot of time >reviewing the code, I can say that it's time to break new ground. If we can >agree on a standard for AsciiDoc / UniDoc, it should be very reasonable to >implement. Obviously, that's a very long-term goal, but there is a future and >we need to prepare for it. Yes a living standard may encourage new implementations, I don't think anyone is believing that the Python 2 implementation is going to be around forever or is the way forward. The stream processing methodology it uses was necessary in the past, but today it is unlikely that documents will be so large that they can't be parsed and loaded into memory all at once. Cheers Lex > Cheers, > > -Dan > > -- > Dan Allen | http://google.com/profiles/dan.j.allen > > -- > 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 http://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 http://groups.google.com/group/asciidoc. For more options, visit https://groups.google.com/d/optout.
