Hi Jens, its always good to get input from another point of view, even if its negative, that helps to see where things might be improved.
To cover many items quickly first.
As you yourself say, items 4-7 are characteristics of the _implementation_ not of Asciidoc markup, so are not relevant to this standardisation effort, but note that it certainly is possible to produce split HTML using a docbook toolchain, but again thats a characteristic of the implementation, not the markup. Similarly your extra tools to provide it without needing docbook is great, I hope your project will contribute them upstream not hoard them and keep complaining upstream doesn't provide it. Same for the extended items, but again thats an implementation specific set of extensions, and as you say specific to a particular type of document your project has produced, it might not be universal enough to include in the language, but is interesting to consider.
Your last paragraph suggests that you have misunderstood the purpose here. This group is to standardise (and improve) Asciidoc, not to specifically promote its use within Eclipse (like Github markup is there).
The other three numbered points are interesting in different ways:
1. the ability to use positional parameters and/or named parameters is pretty common in programming languages, and so is well understood by such users I expect, and has proven its utility in millions of lines of code in various languages. The addition of tagged parameters (the dot hash etc) as shortcuts for named parameters is just another syntax for them, but certainly novel. Clearly however that analogy is not clear to non-programmer users, and needs to be more clearly defined and better documented. Thats something to add to the standard's TODO list.
2. To quote the link you gave "The AsciiDoc version is, arguably, easier to write. You don’t need to worry about indentation.". And to my mind thats the point, nobody these days reads the raw text unless they are writers, and writers need the _expression_ to be well defined and clear. All consumers read the processed result and so the "issues" of the source markup are irrelevant to them. The "readable raw text" thing is an irrelevance these days IMO.
3. I'm not sure I understand your statement here? If its just that the language isn't specified, well, thats the point of the standards process. Certainly there are constructs that are delimited and constructs that are not, but to my mind its pretty clear how blocks and nesting work, so its interesting to try to understand where its confusing to others. Perhaps you can expand on it.
Your linked example is indeed truly awful, but my question is, why? What has prompted the writer to manually define the IDs for every heading in the document? Is it that they don't trust, or just don't understand, the automatic id generation? And the application of roles to many items smacks of someone trying to force presentational semantics on structural markup. As an example a "language-bash" role on a section heading "Parser Generation Post-Processing" seems weird, I guess they must have some funky custom CSS.
Cheers
Lex
Hi,
After many years using Asciidoc in larger projects I have come to the conclusion that Asciidoc is not a good foundation for writing technical documentation though. Some reasons are:
- The syntax is not consistent. There are different syntax constructs for different things. E.g., setting parameters for certain elements does not follow a single concept. In some cases a dot is used as prefix, sometimes not, in other cases assignments are used ([.xxx] vs. [xxx] vs. [xxx=yyy]). And the “+” sign at the end of a line is really a pretty bad idea.
- The syntax is not intuitive nor readable. The Github flavored markdown spec contains a nice comparison of Asciidoc vs markdown (https://github.github.com/gfm/#what-is-markdown-). I think the example is self-explaining.
- There is no clear definition of blocks and nesting. This makes it really hard for longer texts to write and read. Some things can be nested, others cannot — very confusing.
- The output cannot be split-up into multiple HTML files. This is a severe issue when it comes to really long documents, which could easily be the case for specifications. You can see the difference here: https://www.eclipse.org/n4js/spec/N4JSSpec.html is the original output of Asciidoctor (with some tweaks, see below), while https://www.eclipse.org/n4js/spec/index.html shows the same specification split up into multiple documents. While the first one needs quite some time to load, the latter loads very fast. I wrote the split-up tool myself, see below as well.
- PDF output is not acceptable. For example, footnotes are not supported. Overall the PDF quality is very poor. So if you use Asciidoc, you are limited to HTML. As a site note: Also epub is not supported.
- Important features for technical documents and specifications are missing, such as special numbered blocks, e.g., for requirements, examples etc. As a consequence no list of these special blocks, such as list of requirements, list of examples etc., can be created.
- Linking is an issue. In particular for documenting software projects, it would be crucial to refer to code (e.g., in the source code repository).
Issues 4 to 7 may be solved with newly written tools — however that would require a lot of effort, basically writing a new Asciidoc processor from scratch. But then there are still the issues 1 to 3, which cannot be solved except for simply not using Asciidoc.
In the Eclipse N4JS project, we have used Asciidoc (and Asciidoctor) for quite some time. The “Specifications” described at
https://www.eclipse.org/n4js/userguides/index.html#_specification are all written with Asciidoc (the page includes links to the output and the Asciidoc source code), and also the N4JS user guide is using Asciidoc. We also use these documents in the Eclipse help, unfortunately the nightly build is currently not working (at least not the macos version), and the special enfore version (available at
https://download.enfore.com/n4js/, you need a double-click to open a folder) has a bug with the N4JS specification in the Eclipse help (but the N4JS articles and user guide are working in the Eclipse help, and they are written in Asciidoc as well).
We extended Asciidoctor with some extensions written in Java (using JRuby), we called that Asciispec. It is available at
https://github.com/NumberFour/asciispec. These extensions added some features needed for technical and software documentation. However, only after we decided to use JRuby (and having spent too much work there already) we came to the conclusion that the JRuby version is not really usable, as it does not contain the whole Asciidoctor API. In other words: Do not use Java for writing Asciidoctor extensions but Ruby. But I would assume that you would have a “new” tool in mind anyway, don’t you?
Instead of establishing an AsciiDoc Working Group, I would recommend to establish an (Eclipse) Markdown Working Group. Markdown is better readable, and it would be possible (as a working group at Eclipse) to define a defined set of extensions (similar to the Github flavor md), a clear definition of blocks (via indention for example) and other things. I would strongly recommend to not use Asciidoc as a base for a software documentation language due to the problems described above.
Best regards,
Jens
asciidoc-wg mailing list
asciidoc-wg@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/asciidoc-wg
