Tweet
Tweet

Slide 1

Slide 1 text

Evolving real-world AsciiDoc® into a specification and how it will help the ecosystem Alexander Schwartz, Principal Software Engineer @ Red Hat FOSDEM | Brussels, BE | 2024-02-01 TM

Slide 2

Slide 2 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 2 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4

Slide 3

Slide 3 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 3 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4

Slide 4

Slide 4 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 4 Get the docs out to the readers! Mission • Authors should focus on content and its structure • Conversion should support multiple targets from a single source • Published documentation educates users and provides answers to their questions Author Convert Publish

Slide 5

Slide 5 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 5 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4

Slide 6

Slide 6 text

6 Author Author, Convert, Publish Write Validate Review CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz Editor vs. IDE vs. Browser vs. CLI

Slide 7

Slide 7 text

7 Writing in an IDE Author, Convert, Publish CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz • Write without distraction • Syntax highlighting • Autocompletion • Grammar and style check

Slide 8

Slide 8 text

8 Writing in an IDE Author, Convert, Publish CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz • Scrolling and navigate the context • Styled Preview • Collaborate using version control

Slide 9

Slide 9 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 9 Author, Convert, Publish Texts and lists Each sentence should be in a separate line. Every blank line creates a new paragraph. You can write *bold* text. _Italic_ works as well text. Lists . work . with . dots to make them numbered and * asterisks * to * make bullet points.

Slide 10

Slide 10 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 10 Author, Convert, Publish Paragraphs and Admonitions [IMPORTANT] -- You can mark a paragraph to be important. -- TIP: There is also the shorter one-line- syntax. ==== This is an example block. Use it to provide examples to your users. ==== ---- This is a listing. You can provide syntax highlighting for XML/Java etc. here. ----

Slide 11

Slide 11 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 11 Author, Convert, Publish Tables Tables are blocks, `|===` marks their beginning and end. .Table title [cols="1,1,3a,1"] |=== |H1 |H2 |H3 |H4 |Cell 1 |Cell 2 |Formatting *of words* works like in _before_ if you switch the column or cell to AsciiDoc format. |Cell 4 |===

Slide 12

Slide 12 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 12 Author, Convert, Publish Embedding Source Code .Standard include [,java] ---- include::Example.java[] ---- :icons: font .Pick a block with callout [,java,indent=0] ---- include::Example.java[tag=sop] ---- <1> this is your first line of Java

Slide 13

Slide 13 text

13 Validating the contents Author, Convert, Publish CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz # .vale.ini StylesPath = .github/styles MinAlertLevel = suggestion Packages = RedHat IgnoredClasses = error-message [*.adoc] BasedOnStyles = RedHat RedHat.TermsErrors = warning https://github.com/errata-ai/vale-action

Slide 14

Slide 14 text

14 Convert Author, Convert, Publish CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz Maven vs. npm vs. CLI vs. … HTML vs. PDF vs. DocBook vs. … Asciidoctor (Ruby, JavaScript, Java) vs. libasciidoc (Go) vs. Asciidoc-hs (Haskell) vs. …

Slide 15

Slide 15 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 15 Command line converters vs. embedding Author, Convert, Publish $ asciidoctor test.adoc asciidoctor: WARNING: test.adoc: line 2: multiple ids detected in style attribute

Slide 16

Slide 16 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 16 Extensions to interact on structural level Author, Convert, Publish Write extensions that • Extend the AsciiDoc syntax by adding new macros • Interact with a document on an AST level • Generate AsciiDoc content that can be rendered in any supported output format • …

Slide 17

Slide 17 text

17 Publish Author, Convert, Publish CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz Antora

Slide 18

Slide 18 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 18 AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung

Slide 19

Slide 19 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 19 AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung • Static site publishing for AsciiDoc content • Generates a simple to host website • Fully automated publishing • Customizable Theme to match your design • Navigation outline • Site Search

Slide 20

Slide 20 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 20 AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung • Page outline • Custom Navigation • Page linking • Redirects when pages have been renamed

Slide 21

Slide 21 text

Author: • Creates content in a well-defined folder structure • Customizes navigation and versions Docu Ops: • Prepares automation scripts for validation and publishing Web Developer: • Customizes the UI theme CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 21 Antora: Roles and responsibilities Author, Convert, Publish my-component ├─ antora.yml └─ modules ├─ ROOT │ ├─ attachments │ ├─ examples │ ├─ images │ ├─ pages │ │ └─ index.adoc │ ├─ partials │ └─ nav.adoc └─ a-named-module └─ pages Quick Start Guide: https://docs.antora.org/antora/3.1/install-and-run-quickstart/

Slide 22

Slide 22 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 22 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4

Slide 23

Slide 23 text

AsciiDoc® and AsciiDoc Language are trademarks of the Eclipse Foundation, Inc. For questions related to these brand guidelines please reach out to the AsciiDoc Working Group. CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 23 AsciiDoc Brand Brand and Language Documentation https://www.eclipse.org/org/artwork/guidelines/asciidoc-brand-guidelines.pdf

Slide 24

Slide 24 text

Visit https://asciidoc.org/ to learn about AsciiDoc and links to all resources. CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 24 AsciiDoc Website Brand and Language Documentation

Slide 25

Slide 25 text

Visit https://docs.asciidoctor.org/asciidoc/latest/ to learn about the language. CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 25 AsciiDoc Language Documentation Brand and Language Documentation

Slide 26

Slide 26 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 26 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4

Slide 27

Slide 27 text

Visit https://gitlab.eclipse.org/eclipse/asciidoc-lang to get involved, and discuss at https://chat.asciidoc.org/ CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 27 AsciiDoc Language Specification Brand and Language Documentation

Slide 28

Slide 28 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 28 Specification Decision Records to agree on a spec Brand and Language Documentation Community and experts agree on how to standardize the behavior in a best backwards compatible way.

Slide 29

Slide 29 text

CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 29 TCK to check compatibility of implemenations Brand and Language Documentation = Document Title body { "name": "document", "type": "block", "attributes": {}, "header": { "title": [ { "name": "text", "type": "string", "value": "Document Title", "location": [{ "line": 1, "col": 3 }, { "line": 1, "col": 16 }] } ], "location": [{ "line": 1, "col": 1 }, { "line": 1, "col": 16 }] }, ...

Slide 30

Slide 30 text

AsciiDoc https://asciidoc.org Asciidoctor https://asciidoctor.org IntelliJ AsciiDoc Plugin https://ahus1.de/post/technical-writing-udemy Links CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 30 @ahus1de @ahus1de Antora https://antora.org/ https://www.ahus1.de/post/documentation-site-antora Videos, slides and examples https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive @ahus1@fosstodon.org @ahus1@fosstodon.org Slides:

Slide 31

Slide 31 text

Contact Alexander Schwartz Principal Software Engineer alexander.schwartz@gmx.net https://www.ahus1.de @ahus1de @ahus1@fosstodon.org CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 31