AsciiDoc Language

Here's my take.

I use AsciiDoc to document:

• Software applications
• Software release notes
• Software APIs
• Protocols
• File formats

This is my bias.

Missing semantics

Graeme Smecher
wrote
on the mailing list:

A friendly mark-up anchored to an industrial-strength document
model is AsciiDoc's killer feature for me. I'm interested in
reducing
the impedance mismatches between AsciiDoc and DocBook.

Having this impedance reduced is also my principal ambition.

I want AsciiDoc to offer as many semantic markup as possible while
remaining as lightweight as possible (otherwise I'd just write
DocBook directly).

Considering this, here's the list DocBook tags of which an equivalent
markup is missing from AsciiDoc (as far as I know) for my use cases:

• General:
  • abbrev
  • acronym
  • date
  • firstterm
  • replaceable
  • see
  • seealso
  • termdef
  • wordasword
• Revision:
  • revdescription
  • revhistory
  • revisiondocument
  • revnumber
  • revremark
• Procedure:
  • procedure
  • result
  • step
  • stepalternatives
  • substeps
• Task:
  • task
  • taskprerequisites
  • taskrelated
  • tasksummary
• Manual page reference:
  • citerefentry
  • manvolnum
  • refentrytitle
• Software (general):
  • command
  • database
  • envar
  • errorcode
  • errorname
  • errortext
  • errortype
  • filename
  • markup
  • menuchoice
  • msg
  • msgaud
  • msgentry
  • msgexplan
  • msginfo
  • msglevel
  • msgmain
  • msgorig
  • msgrel
  • msgset
  • msgsub
  • msgtext
  • optional
  • package
  • prompt
  • property
  • screenshot
  • synopsis
  • systemitem
  • uri
  • userinput
• GUI (software):
  • accel
  • guiicon
  • guilabel
  • mousebutton
• Command description (software):
  • arg
  • cmdsynopsis
  • command
  • option
  • sbr
• Software programming:
  • classname
  • classsynopsis
  • classsynopsisinfo
  • constant
  • constructorsynopsis
  • exceptionname
  • fieldsynopsis
  • funcdef
  • funcparams
  • funcprototype
  • funcsynopsis
  • funcsynopsisinfo
  • function
  • initializer
  • interfacename
  • methodname
  • methodparam
  • methodsynopsis
  • modifier
  • ooexception
  • oointerface
  • paramdef
  • parameter
  • returnvalue
  • symbol
  • tag
  • token
  • type
  • varargs
  • variablelist
  • varname
  • void

I get that for many inline elements, you can use hash symbols
with a custom class:

Pass an [.type]#std::string# object to the [.func]#setName# function.

Is this the intention? If so, it's still not specified and up to the
writer. I suggest to formalize this, using another syntax than the
class attribute, for example:

Pass an [:type]#std::string# object to the [:function]#setName#
function.

Syntax improvements

Here are a few syntax improvement suggestions, in order of importance
for me.

List item continuation

As a tech writer, what I use the most outside paragraphs are lists:
unordered, ordered, and description.

Those lists often contain items which can get rather complex.
I've always had a hard time dealing
with list item continuation in AsciiDoc. I find the + syntax is
annoying at best. Sure you can use open blocks, but
you
can't nest them:

* This is a list item.
+
It continues here.
+
And here.

* Sure you can use an open block:
+
--
Like this!

But then what if you want to nest another list here?

* You can.
+
But you can't use an open block because the beginning and end delimiters
are the same.
--
+
First level continued.

Also, I find the "unnesting" syntax, where the number of newlines above the
following + on a single line indicates how many levels to
go back, very confusing:

* Level 1.
** Level 2.
+
Some more level 2 content.
+
*** Level 3.
+
Level 3 continued.

+
Level 2 continued.
*** Other level 3.
+
Other level 3 continued.

+
Level 1 continued.

* Other level 1.

Is this readable to you?

This issue (for me at least) includes the syntax to nest lists, where
you use more *, more ., or more :
depending on the list type when not using open blocks:

* Level 1.
** Level 2.
... Level 3.
** Other level 2.
Question:::
Answer.
Subpoint::::
Subpoint content.
+
Subpoint continued.
Other subpoint::::
Other subpoint content.
Other question:::
Other answer.

** Yet another level 2.

I know AsciiDoc does not rely on indentation usually, but what I'm
suggesting is make an exception here, at least optionally, to nest lists and
to continue list items, just like Markdown does.
There might be limitations, but as far as I know I see none.

Here are the two previous examples reformatted to use identation to
nest and continue items:

* Level 1.
* Level 2.

Some more level 2 content.

* Level 3.

Level 3 continued.

Level 2 continued.

* Other level 3.

Other level 3 continued.

Level 1 continued.

* Other level 1.

* Level 1.
* Level 2.
. Level 3.
* Other Level 2.

Question::
Answer.

Subpoint::
Subpoint content.

Subpoint continued.

Other subpoint::
Other subpoint content.

Other question::
Other answer.

* Yet another level 2.

Nested open blocks

As mentioned above, you can't nest open blocks.

The suggested solution in the GitHub issue is to use ~~~~
to delimit open blocks, adding more ~ to nest them:

~~~~
An open block.

~~~~~
A nested open block.
~~~~~

Continued open block.
~~~~

While this at least provides a solution, why not use a dedicated
closing delimiter instead?

Here's an example, reusing the -- delimiter
we know to begin an open block:

--
An open block.

--
A nested open block.
/-

Continued open block.
/-

There might be forms that are more visually appealing. For example,
using < to open and > to close on
single lines:

<
An open block.

<
A nested open block.
>

Continued open block.
>

In fact, why not use this strategy for any nestable block?

Block title

According to
Title:

A block title is defined on a line above the element. The line must
begin with a dot (.) and be followed immediately by the
title text.

Example:

.Using `printf()` with a signed integer.
====
[source,c]
----
printf("here's an integer: %d\n", 23);
----
====

Sometimes the block title can be long, especially for example titles.

I therefore suggest to have a way to continue the title on the
following line(s) in some way. For example, using a single space
on the following lines:

.Using `printf()` with a signed integer, an unsigned integer,
and a C{nbsp}string.
====
[source,c]
----
printf("here's a bunch of stuff: %d, %u, `%s`\n", 23, 77U, "hello");
----
====

Dedicated non-breaking space and hyphen shorthands

I often need non-breaking spaces. I use them between:

• Numbers and units
• Project names and versions
• Titles and first names
• Days and months
• Months and years

and more.

You can use {nbsp} to write a non-breaking space and
‑ to write a non-breaking hyphen.

I suggest to have built-in shorthands for both of them. LaTeX uses
~ for a non-breaking space.

Macros

AsciiDoc (Python) has macros and attributes while Asciidoctor has
extensions (Ruby/Java/JavaScript) and attributes.

Should the AsciiDoc specification include an official macro language?

What I mean by macro is a template of AsciiDoc content with variable
placeholders. The expanded macro can become block content or inline
content.

Here's a fictitious example:

:func: https://myproject.org/docs/v{#1}/{#2}.html[`{#2}()`]

See the {web 3.2 replaceText} and {web 3.4 substitute} functions for
more details.

Here's another example for block content:

:rlq:
[quote, René Lévesque, Défaite du Oui au référendum de 1980]
{#1}

You can't always get what you want, as Jagger sang.

{rlq
"Si j'ai bien compris, vous êtes en train de me dire{nbsp}:
à la prochaine fois."}

But those who dare to fail miserably can achieve greatly.

I'm the current maintainer of the AsciiDoc IntelliJ plugin, and I'm taking the perspective of a IDE-plugin developer for this comment.

Please reply and let me know if you second any of these ideas for the scope of the proposals, or if you consider them part of the existing proposal.

From an IDE perspective I'd like to see the following elements to be part of the scope:

1. Retrieve meta-information at runtime for auto-complete of macros, preprocessor-directives and attributes 
2. Mapping output to the source input, to allow the user to trace back an output in the preview to a source line
3. Extentions should provide an abstraction to the file system and references to allow advanced reference/content systems like Antora.
4. Extensions should be ordered. They should be able to hook into the processing and delegate to a previous implementation. This way an extension could add an attribute to an existing macro, or convert an attribute's content before delegating it to the original implementation.
5. For spell checking an adoc-file meta-information should be available to find out what parts of a macro contain information that should be spell checked 

ad 1: The meta-information at runtime should include built-in and active extensions for a list of available macros and attributes. Each macro and attribute should provide a textual self-description for a (human) writer. Each macro (extension or built-in) should provide a list of supported attributes. Each attribute should provide a sample and default value and possibly also a type so that the IDE can trigger auto-complete for file names, IDs, etc. 

ad 2: The Asciidoctor HTML output already implements it by adding additional data attributes to some HTML tags, but doesn't attach it to all tags. It is currently based on line level. Future implementations could provide line and column information. Sourcemaps would be a method of implementation, but might depend on the output.

ad 3: I assume this is covered by either "Internal and external referencing system" or the Extension API "(path) resolvers", I just want to make sure either of them can be used for this.

ad 4: When retrofitting some Antora style behavior to Asciidoctor Ruby I used "prepend" to monkey-patch some of the necessary functionality. With a mechanism as described above this would not have been necessary.

Just please don't rename it to  "Eclipse AsciiDocium".

I would go for the procedure and the task suggestions.

Those two alone will standardize at least 70% of my content issues.