Improve documentation for converting from Asciidoc Python?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Improve documentation for converting from Asciidoc Python?

rockyallen
I just had a problem identifying a replacement for the Asciidoc Python indir built in attribute. This is now solved, but It was not easy to locate the information in the current Asciidoctor documentation.

1. In the Asciidoc Python user guide, the list of attributes is centralised in
http://www.methods.co.nz/asciidoc/userguide.html#X60. In Asciidoctor it is fragmented across a guide (http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs), Appendix A (http://asciidoctor.org/docs/user-manual/#asciidoctor-vs-asciidoc), Appendix B (http://asciidoctor.org/docs/user-manual/#char-ref-table) and Section 12.4 (http://asciidoctor.org/docs/user-manual/#built-in-data-attributes).

2. http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs confuses me because it seems to contain a mix of built in attributes, syntax and allowable attribute values.

3. I do not understand the difference (to an author)  between the 2 tables in Annex B.

Possible improvements:

1. Copy http://www.methods.co.nz/asciidoc/userguide.html#X60 to http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs and add a column indicating the Asciidoctor replacement, or

2. Expand (and possibly break up) the table in Appendix A: add all Asciidoc Python attributes; add explanations; add links into the body of the document.

3. Expand Appendix B to cover all Asciidoctor attributes like the Asciidoc Python user manual.

I am willing to have a go if there is an agreed way forward.
Reply | Threaded
Open this post in threaded view
|

Re: Improve documentation for converting from Asciidoc Python?

mojavelinux
Administrator
In general, I'm in favor of more clarity. I realize we still have a ways to go to get there, so let's keep pressing forward.

I've always wanted to have a clear itemization of the intrinsic attributes as well as the list of available attributes. You are correct that the current table is jumbling these all together, as well as attributes specific to a block. We need a better organization.

I don't really want to focus on AsciiDoc Python in the core part of the guide. I'm okay with having an appendix about migrating (Migrating from AsciiDoc Python), but AsciiDoc Python is in the past and I want that to be the position of the Asciidoctor user manual.

Would you mind opening an issues in the https://github.com/asciidoctor/asciidoctor.org repository about creating a dedicated table for (a) intrinsic attributes and (b) available document-level attributes. Please file separate issues since these are different tasks.

Thanks!

-Dan

On Thu, Jan 21, 2016 at 2:25 PM, rockyallen [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I just had a problem identifying a replacement for the Asciidoc Python indir built in attribute. This is now solved, but It was not easy to locate the information in the current Asciidoctor documentation.

1. In the Asciidoc Python user guide, the list of attributes is centralised in
http://www.methods.co.nz/asciidoc/userguide.html#X60. In Asciidoctor it is fragmented across a guide (http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs), Appendix A (http://asciidoctor.org/docs/user-manual/#asciidoctor-vs-asciidoc), Appendix B (http://asciidoctor.org/docs/user-manual/#char-ref-table) and Section 12.4 (http://asciidoctor.org/docs/user-manual/#built-in-data-attributes).

2. http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs confuses me because it seems to contain a mix of built in attributes, syntax and allowable attribute values.

3. I do not understand the difference (to an author)  between the 2 tables in Annex B.

Possible improvements:

1. Copy http://www.methods.co.nz/asciidoc/userguide.html#X60 to http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs and add a column indicating the Asciidoctor replacement, or

2. Expand (and possibly break up) the table in Appendix A: add all Asciidoc Python attributes; add explanations; add links into the body of the document.

3. Expand Appendix B to cover all Asciidoctor attributes like the Asciidoc Python user manual.

I am willing to have a go if there is an agreed way forward.



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Improve-documentation-for-converting-from-Asciidoc-Python-tp4216.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Improve documentation for converting from Asciidoc Python?

rockyallen
In reply to this post by rockyallen