<xs:schema ...>
<!-- hello world from an xml comment -->
</xs:schema>
There is a trend towards less WYSIWYG for documentation, slides, etc. because it doesn’t have the useful characteristics of source code in that it cannot be easily diffed. Configuration management is always more ad-hoc and problematic. AsciiDoc is a highly regular markdown-style language for creating documentation in the style of Markdown, but it eliminates many drawbacks of the various markdown dialects.
This page itself is AsciiDoc. Jekyll converts it to HTML using Asciidoctor.
|
When writing asciidoc, or any other markdown, or even html or xml or tdml tutorial, etc. The point is to treat this stuff like code - i.e., have line-diffs be useful. In order for that to work really well, you need to use the one sentence-per-line writing technique. |
A primary reason to use asciidoc is the support for diagrams created via text. Many kinds are supported directly. See Asciidoctor diagram.
Let’s look at some kinds of content.
<xs:schema ...>
<!-- hello world from an xml comment -->
</xs:schema>You should consider using AsciiDoc for slide-ware instead of something like powerpoint.
Slide full of bullets
Slide full of bullets
Slide full of bullets
Slide full of bullets
Images work in the basic way. Here’s an inline image
,
and here’s the same image as an image block:
There are numerous kinds of diagrams possible.
PlantUML is a component that allows to quickly write:
Sequence diagram
Usecase diagram
Class diagram
Activity diagram (here is the legacy syntax)
Component diagram
State diagram
Object diagram
Deployment diagram
Timing diagram
The following non-UML diagrams are also supported:
Wireframe graphical interface
Archimate diagram
Specification and Description Language (SDL)
Ditaa diagram
Gantt diagram
MindMap diagram
Work Breakdown Structure diagram
Mathematic with AsciiMath or JLaTeXMath notation
Entity Relationship diagram
An www.plantuml.com/plantuml/uml[online PlantUML authoring tool] is available. Though just saving and refreshing the page in a web browser (usually they auto-refresh after 1 second) is also pretty easy.
Here is a class diagram example:
Here’s a PlantUML Sequence Diagram:
The DITAA graphics are ASCII-Art converted into smoother looking drawings. They have the advantage of being visual in the text file.
These diagrams are quite easily drawn then cut/pasted to/from actual asciidoc digrams using an online tool called asciiflow.
Note: below is the widest ditaa diagram you can draw that will fit in the line-length that github’s code-review/pull-request window can display without line-wrap. If the lines wrap in your ditaa diagram you really lose the ability to comment on them in their textual form in the asciidoc:
GraphViz is probably the most powerful of the various diagram tools, but with that power comes complexity that some of the other diagram types are able to overcome by being more restrictive.
This is an example of graphViz Record-based Nodes which are very useful for box diagrams showing data layouts when a packetdiag is too rigid.
Random boxes and ovals and other shapes.
