search

asciidoctor / asciidoctor

:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.
https://asciidoctor.org
Other
4.84k stars 790 forks source link

Add high-level program flow documentation #1954

Closed fapdash closed 7 years ago

fapdash commented 7 years ago

Maybe I missed it but I couldn't find program flow documentation for Asciidoctor. I think this would help new contributors to get productive faster.

I had a go at a sequence diagram that shows how Asciidoctor, Document and the Converter interact on a high level. asciidoctor_sequence_highlevel

If someone wants to fix errors:

@startuml
"/bin/asciidoctor" -> "CLI:Invoker": invoke!
"CLI:Invoker" --> "::Asciidoctor": convert
"::Asciidoctor" --> "::Asciidoctor": load (Parse the AsciiDoc source input into an Asciidoctor::Document)
"::Asciidoctor" --> "::Asciidoctor::Document": parse (Parse the AsciiDoc source stored in the Reader into an abstract syntax tree.)
"::Asciidoctor" --> "::Asciidoctor::Document": convert (returns either converted String or filled Converter Object e.g. PdfConverter)
"::Asciidoctor" --> "::Asciidoctor::Document": write (either writes String directly to file or delegates to Converter first)
@enduml

https://www.planttext.com/

mojavelinux commented 7 years ago

I'd love to see a diagram like this in the documentation. However, could you open this issue against the asciidoctor.org repository, which is where the user manual resides (unless you think we need this diagram in this README too).

fapdash commented 7 years ago

Oh, I thought this would be the right place since the contribution guide is in this repo and the asciidoctor.org page links to it.

fapdash commented 7 years ago

Opened https://github.com/asciidoctor/asciidoctor/issues/4515

mojavelinux commented 7 years ago

You're correct that the instructions for submitting documentation requests is not clear. That's partly because we still haven't completely resolved where the documentation should live...so the confusion is on our end. I really don't want the documentation to live on the asciidoctor.org site, but that's where we are today. (I'd rather see it either in a dedicated repository or belong to each project, then get pulled into asciidoctor.org).