Downloaded 15 times
![AsciiDoc example = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-3-2048.jpg)
![AsciiDoc example = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-5-2048.jpg)
![Headings = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Document Title Section Level 1](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-6-2048.jpg)
![= Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Lists Unordered list items](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-7-2048.jpg)
![Inline formatting = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. bold italic code](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-8-2048.jpg)
![= Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Links link with title](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-9-2048.jpg)
![= Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Admonition](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-10-2048.jpg)
![A code snippet in your documentation == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML. [[lst-wikitext1, Listing 1]] [source,java] ---- public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), n parser.parse(mediawikiText); return writer.toString(); } ----](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-16-2048.jpg)
![Callout == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML. [[lst-wikitext1, Listing 1]] [source,java] ---- public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), n parser.parse(mediawikiText); // <1> return writer.toString(); } ---- <1> Main call of the Mylyn Wikitext framework](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-17-2048.jpg)
![ code snippets corresponding to source code under control − Always up-to-date − Ease maintenance Real source code in your documentation == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML. [[lst-wikitext1, Listing 1]] [source,java] ---- include::src/main/java/MediawikiTest.java[tags=method] ---- <1> Main call of the Mylyn Wikitext framework](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-20-2048.jpg)
![Real source code in your documentation public class MediawikiTest { //tag::method[] public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), new H parser.parse(mediawikiText); // <1> return writer.toString(); } //end::method[] @Test public void test() { StringBuilder sb = new StringBuilder(); sb.append("= Heading 1 =n"); sb.append("n"); sb.append("Hello World!n"); sb.append("n"); sb.append("* Loremn");](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-21-2048.jpg)
![Variable substitution Open source projects at the Eclipse Foundation are required to make use of certain Eclipse Foundation services: * All project issues must be tracked in the {bugzillaUrl}[{forgeName} Bugzilla]instance; :forgeName: Eclipse :bugzillaUrl: https://bugs.eclipse.org/bugs Eclipse Project Handbook ======================== include::chapters/resources.adoc[] eclipse.adoc resources.adoc](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-25-2048.jpg)
![Variable substitution Open source projects at the Eclipse Foundation are required to make use of certain Eclipse Foundation services: * All project issues must be tracked in the {bugzillaUrl}[{forgeName} Bugzilla]instance; :forgeName: LocationTech :bugzillaUrl: https://www.locationtech.org/bugs LocationTech Project Handbook ============================= include::chapters/resources.adoc[] locationtech.adoc resources.adoc](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-26-2048.jpg)
![Conditional inclusion ifeval::["{forgeName}"=="Eclipse"] _The Eclipse Foundation strongly encourages all projects to create an maintain and http://marketplace.eclipse.org[Eclipse Marketplace] presence._ endif::[]](https://image.slidesharecdn.com/orzjpreoqcwrfbq3dpun-signature-940cd114dec6cf61746d4eba14a63bda227a973e51cc87ea13f3e0c206c28d11-poli-160816103239/75/Writing-documentation-with-Asciidoctor-27-2048.jpg)
Uploaded byJérémie Bresson
Writing documentation with Asciidoctor
The document provides a comprehensive guide on writing documentation using Asciidoctor and includes a 'Hello World' Java example, detailing the compilation and execution process. It also covers various features of Asciidoctor, such as multiple output formats, variable substitution, and integration with different build systems. Additionally, it contains code snippets for converting MediaWiki text to HTML and discusses best practices for maintaining source code within documentation.
Writing documentation with Asciidoctor
- 1. Jérémie Bresson –03.11.2015 Writing documentation with Asciidoctor
- 2.
- 3. AsciiDoc example = GettingStarted with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
- 4.
- 5. AsciiDoc example = GettingStarted with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
- 6. Headings = Getting Startedwith Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Document Title Section Level 1
- 7. = Getting Startedwith Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Lists Unordered list items
- 8. Inline formatting = GettingStarted with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. bold italic code
- 9. = Getting Startedwith Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Links link with title
- 10. = Getting Startedwith Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Admonition
- 11.
- 12. Asciidoctor ispublishing toolchain for the AsciiDoc writing format. Written in Ruby (and transpiled to JavaScript) (can be used with JRuby in the JVM) Open Source (MIT Licence) Asciidoctor
- 13. Multiple Outputs PDF HTML pages Eclipse Help guides
- 14. «Why is asciidoctora great tool?»
- 15.
- 16. A code snippetin your documentation == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML. [[lst-wikitext1, Listing 1]] [source,java] ---- public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), n parser.parse(mediawikiText); return writer.toString(); } ----
- 17. Callout == Usage ofMylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML. [[lst-wikitext1, Listing 1]] [source,java] ---- public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), n parser.parse(mediawikiText); // <1> return writer.toString(); } ---- <1> Main call of the Mylyn Wikitext framework
- 18.
- 19. Callout – Copypaste friendly
- 20. code snippetscorresponding to source code under control − Always up-to-date − Ease maintenance Real source code in your documentation == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML. [[lst-wikitext1, Listing 1]] [source,java] ---- include::src/main/java/MediawikiTest.java[tags=method] ---- <1> Main call of the Mylyn Wikitext framework
- 21. Real source codein your documentation public class MediawikiTest { //tag::method[] public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), new H parser.parse(mediawikiText); // <1> return writer.toString(); } //end::method[] @Test public void test() { StringBuilder sb = new StringBuilder(); sb.append("= Heading 1 =n"); sb.append("n"); sb.append("Hello World!n"); sb.append("n"); sb.append("* Loremn");
- 22. Single source yourdocuments
- 23. «AsciiDoc lets medo variable substitution and conditional inclusion» Wayne Beaton, Eclipse Foundation https://waynebeaton.wordpress.com/2015/08/10/new-eclipse-project-handbook/
- 24. One source, multipleoutput Eclipse Fundation Handbook LocationTech Handbook PolarSys Handbook …
- 25. Variable substitution Open sourceprojects at the Eclipse Foundation are required to make use of certain Eclipse Foundation services: * All project issues must be tracked in the {bugzillaUrl}[{forgeName} Bugzilla]instance; :forgeName: Eclipse :bugzillaUrl: https://bugs.eclipse.org/bugs Eclipse Project Handbook ======================== include::chapters/resources.adoc[] eclipse.adoc resources.adoc
- 26. Variable substitution Open sourceprojects at the Eclipse Foundation are required to make use of certain Eclipse Foundation services: * All project issues must be tracked in the {bugzillaUrl}[{forgeName} Bugzilla]instance; :forgeName: LocationTech :bugzillaUrl: https://www.locationtech.org/bugs LocationTech Project Handbook ============================= include::chapters/resources.adoc[] locationtech.adoc resources.adoc
- 27. Conditional inclusion ifeval::["{forgeName}"=="Eclipse"] _The EclipseFoundation strongly encourages all projects to create an maintain and http://marketplace.eclipse.org[Eclipse Marketplace] presence._ endif::[]
- 28. Simple Tools (nosetup)
- 29.
- 30. Extension forChrome: Asciidoctor.js Live Preview Live preview in Chrome
- 31. JavaFX Codeeditors –Tom Schindl
- 32.
- 33. «Generating the documentation with Asciidoctoris always a straightforward experience» Julien Ponge, Eclipse Golo project https://julien.ponge.org/blog/an-experiment-in-maven-to-gradle-migration/
- 34. Ruby, JavaScript,JVM environments Integration with a lot of build systems: − Maven − Gradle Dependencies available in several repositories − Maven central − JCenter − NPM You can build on every machine, without a complex setup Build system
- 35.
- 36.
- 37.
- 38.
- 39.