From 8d23f85179f28b083f0376d4e052964cc7824b5a Mon Sep 17 00:00:00 2001 From: Sturt Ison Date: Sun, 15 Oct 2023 07:27:12 +0300 Subject: [PATCH] Separate use-cases and quick start pages: (#652) (#654) Create separate pages from existing content into: * use-cases.adoc * quickstart.adoc * diagrams-extension-quickstart.adoc Update nav.adoc. --- changelog.adoc | 2 + docs/modules/ROOT/nav.adoc | 5 +- .../ROOT/pages/custom-attributes-option.adoc | 2 +- .../ROOT/pages/diagrams-extension-option.adoc | 91 +++------ .../pages/diagrams-extension-quickstart.adoc | 64 +++++++ docs/modules/ROOT/pages/features.adoc | 179 +----------------- docs/modules/ROOT/pages/quickstart.adoc | 37 ++++ docs/modules/ROOT/pages/use-cases.adoc | 133 +++++++++++++ 8 files changed, 269 insertions(+), 244 deletions(-) create mode 100644 docs/modules/ROOT/pages/diagrams-extension-quickstart.adoc create mode 100644 docs/modules/ROOT/pages/quickstart.adoc create mode 100644 docs/modules/ROOT/pages/use-cases.adoc diff --git a/changelog.adoc b/changelog.adoc index defa668b..3ddadf45 100644 --- a/changelog.adoc +++ b/changelog.adoc @@ -2,6 +2,8 @@ == Unreleased +* Docs: reorganize use-cases to separate page, try-it-yourself to a quickstart page, diagrams try-it-yourself to a diagrams quickstart page (#652) (#654) + == 2.7.1 (2023-06-03) * Add `accept` header when fetching AsciiDoc content (mainly to workaround an issue on github.com) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index c82151fc..7004a67d 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,4 +1,5 @@ * xref:install.adoc[] +* xref:quickstart.adoc[] * xref:features.adoc[] * xref:options.adoc[] ** xref:custom-attributes-option.adoc[] @@ -6,4 +7,6 @@ ** xref:theme-stylesheet-option.adoc[] ** xref:javascript-option.adoc[] ** xref:load-the-javascript-option.adoc[] -* xref:firefox-known-issues.adoc[Known issues] \ No newline at end of file +* xref:diagrams-extension-quickstart.adoc[] +* xref:use-cases.adoc[] +* xref:firefox-known-issues.adoc[Known issues] diff --git a/docs/modules/ROOT/pages/custom-attributes-option.adoc b/docs/modules/ROOT/pages/custom-attributes-option.adoc index f2d2911a..9fbdce07 100644 --- a/docs/modules/ROOT/pages/custom-attributes-option.adoc +++ b/docs/modules/ROOT/pages/custom-attributes-option.adoc @@ -36,7 +36,7 @@ See section xref:features.adoc#set-asciidoc-attributes[Set AsciiDoc attributes] == Use cases -For more ideas and use cases for setting attributes, see section xref:features.adoc#use-cases[Use cases] on the features page. +For more ideas and use cases for setting attributes, see the xref:use-cases.adoc[] page. == AsciiDoc Attributes diff --git a/docs/modules/ROOT/pages/diagrams-extension-option.adoc b/docs/modules/ROOT/pages/diagrams-extension-option.adoc index f100e1f7..5de00383 100644 --- a/docs/modules/ROOT/pages/diagrams-extension-option.adoc +++ b/docs/modules/ROOT/pages/diagrams-extension-option.adoc @@ -2,25 +2,29 @@ :navtitle: Diagrams extension :keywords: kroki,diagrams like code,diagrams -With the extension option *Diagrams extension* you can embed diagrams in your AsciiDoc files as text based descriptions using the https://kroki.io[Kroki.io] online service. +On this page you will learn: -The Kroki server (default or custom) converts the text to its corresponding image. -You do not need any other software installed on your machine or browser. +* [x] about the diagrams extension +* [x] about Kroki +* [x] how to configure the extension option *Diagrams extension* +* [x] a simple example -On this page you will find: +For a more complex example, see the xref::diagrams-extension-quickstart.adoc[] page. -* [x] how to configure the extension option *Diagrams extension* -* [x] an example -* [x] a try-it-yourself example. +== Use Kroki via the diagrams extension + +With the extension option *Diagrams extension* you can embed diagrams in your AsciiDoc files as text based descriptions using the https://kroki.io[Kroki.io] online service. + +The Kroki server (default or custom) converts the text to its corresponding image with no extra software installed on your machine or browser. To learn more about diagrams from text based descriptions and "diagrams like code", visit https://kroki.io. == Diagrams extension options -There are two options for the diagrams extension: +The two options of the diagrams extension are: -* Enable the diagrams extension -* The Server URL +* Enabled or disabled +* Kroki Server URL === Enable the diagrams extension @@ -60,8 +64,17 @@ Diagrams from text in general enables further documentation automation. The benefits of running Kroki locally, or installing it on your own infrastructure are: * Diagram conversion traffic remains inside your organization + * Depending on the diagram generator used, you may standardise diagram themes for consistency across your organization without changing source diagrams +=== Security, diagrams and Kroki + +Using Kroki via the diagrams extension removes the need to install and maintain diagramming software on individual machines, centralising their deployment to a central Kroki server. + +To satisfy security policies, organizations may choose to deploy a Kroki service within their own network. + +=== Learn more Kroki + Learn more about installing Kroki at https://kroki.io == Example diagram @@ -83,60 +96,6 @@ digraph { rankdir=LR a -> b -> c} For more information about embedding diagrams as text and GraphViz diagrams, visit https://kroki.io and https://graphviz.org. -== Try it yourself - -Below is an example diagram showing communication between the Diagrams extension and the Kroki.io server set by the *Server URL* in xref:options.adoc[]. - -You'll create the AsciiDoc file that both holds and displays the diagram when viewed with the {project-name}. - -The diagram below uses the PlantUML diagram generator. -To learn more about embedding diagrams, other diagram languages and PlantUML, visit https://kroki.io and https://plantuml.com. - -.Diagrams extension sequence -image::diagrams-extension-sequence.svg[] - -To create the above diagram after installing the {project-name}, do the following: - -. Create a file "diagram-extension-example.adoc" with the following contents: -+ -.diagram-extension-example.adoc -[,asciidoc] ----- -= Diagrams extension example with Kroki.io - -The sequence diagram is below: - -[plantuml] -.... -@startuml -entity "Local or remote file" as file -box Browser #white -participant Browser as browser -participant "Asciidoctor\nBrowser Extension" as extension -box "Kroki Server" #white -participant "Kroki Gateway" as kroki -participant "Diagram generator" as generator -end box -file -> browser : AsciiDoc -browser -> extension : AsciiDoc -activate extension -extension -> kroki : encoded diagram text -kroki -> generator : diagram text -kroki <- generator : image -extension <- kroki : image -browser <- extension : HTML5 -deactivate extension -@enduml -.... ----- - -. Enable the Diagrams extension with the default *Server URL* from the extension options. -For help enabling and disabling the Diagrams extension, see the xref:options.adoc[] page. - -. Open or reload the above file in the browser to see the diagram. - -. Modify the diagram text in the AsciiDoc and reload the page to see your updated diagram. +== Quickstart -. Disable the Diagrams extension. -+ -IMPORTANT: Disable the Diagrams extension to stop communication with the *Server URL*. +To try it your yourself, visit the xref::diagrams-extension-quickstart.adoc[] page. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/diagrams-extension-quickstart.adoc b/docs/modules/ROOT/pages/diagrams-extension-quickstart.adoc new file mode 100644 index 00000000..c262c86d --- /dev/null +++ b/docs/modules/ROOT/pages/diagrams-extension-quickstart.adoc @@ -0,0 +1,64 @@ += Diagrams extension quickstart + +In this quick start you'll: + +* [x] create an AsciiDoc file that both holds and displays a diagram when viewed with the {project-name} +* [x] configure the extension to use Kroki +* [x] view the converted diagram +* [x] stop the extension using Kroki + +Below is an example diagram showing communication between the Diagrams extension and the Kroki.io server set by the *Server URL* in xref:options.adoc[]. + +.Diagrams extension sequence +image::diagrams-extension-sequence.svg[] + +The diagram above uses the PlantUML diagram generator via Kroki. +To learn more about embedding diagrams, other diagram languages and PlantUML, visit https://kroki.io and https://plantuml.com. + +== Steps + +To create the above diagram after installing the {project-name}, do the following: + +. Create a file "diagram-extension-example.adoc" with the following contents: ++ +.diagram-extension-example.adoc +[,asciidoc] +---- += Diagrams extension example with Kroki.io + +The sequence diagram is below: + +[plantuml] +.... +@startuml +entity "Local or remote file" as file +box Browser #white +participant Browser as browser +participant "Asciidoctor\nBrowser Extension" as extension +box "Kroki Server" #white +participant "Kroki Gateway" as kroki +participant "Diagram generator" as generator +end box +file -> browser : AsciiDoc +browser -> extension : AsciiDoc +activate extension +extension -> kroki : encoded diagram text +kroki -> generator : diagram text +kroki <- generator : image +extension <- kroki : image +browser <- extension : HTML5 +deactivate extension +@enduml +.... +---- + +. Enable the Diagrams extension with the default *Server URL* from the extension options. +For help enabling and disabling the Diagrams extension, see the xref:options.adoc[] page. + +. Open or reload the above file in the browser to see the diagram. + +. Modify the diagram text in the AsciiDoc and reload the page to see your updated diagram. + +. Disable the Diagrams extension. ++ +IMPORTANT: Disable the Diagrams extension to stop communication with the *Server URL*. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc index 738a9e58..d30fcaa9 100644 --- a/docs/modules/ROOT/pages/features.adoc +++ b/docs/modules/ROOT/pages/features.adoc @@ -5,7 +5,7 @@ The main feature is viewing AsciiDoc as HTML5 directly in the browser. Other features cover where those AsciiDoc files are located, and how they are rendered. -You can exercise these features in the <> section of this page. +You can exercise these features by using the xref:quickstart.adoc[] page. [#example] == View AsciiDoc as HTML5 @@ -15,7 +15,7 @@ The screen capture below shows raw AsciiDoc on the left, and rendered HTML5 on t If the extension is inactive, you'll see the raw AsciiDoc. If it is active, you'll see the rendered HTML5. -Reproduce this example yourself by following the instructions further below in <>. +Reproduce this example yourself by following the instructions in the xref:quickstart.adoc[] page. image::{url-asciidoctor-sc-image}["Screen capture of two screens, showing raw AsciiDoc and rendered as HTML5"] @@ -165,177 +165,4 @@ This may save you time: Learn more about these two text markup formats at: * xref:asciidoc::asciidoc-vs-markdown.adoc[Compare AsciiDoc to Markdown] via AsciiDoc (the language) -* xref:asciidoctor:migrate:markdown.adoc[Migrate from Markdown to Asciidoctor] via Asciidoctor (the generator) - -[#try-it-yourself] -== Try it yourself - -To reproduce the example shown in <>, do the following: - -:exfile: ex-writing-zen.adoc - -. Install the {project-name} using the xref:install.adoc[] page -. Create `{exfile}` from the text below or xref:attachment${exfile}[download] it. -+ -.ex-writing-zen.adoc ------ -include::attachment${exfile}[] ------ - -. Open `{exfile}` in your browser. You may either: - -* Open it by pressing kbd:[Control,O] -* Drag and drop `{exfile}` onto your browser -* Double-click `{exfile}` -+ -NOTE: For double-click to work, you may need to change your computer settings to associate `.adoc` with your web browser. - -. Try different features with the following: - -.. Toggle the {project-name} activation by clicking its extension icon in the browser bar. -+ -You'll see the AsciiDoc behind the rendered HTML page. -.. Change the xref:theme-stylesheet-option.adoc[] and reload. -.. Change the Theme/Stylesheet using a query parameter. -Add `stylesheet=github` to the end of the URL. -.. Edit the AsciiDoc file and save. -Observe it update. -.. Add `toc=left` to xref:custom-attributes-option.adoc[], and reload. - -. Next steps -+ -After the above, you may like to try the exercise in the xref:diagrams-extension-option.adoc[]. - -[#use-cases] -== Use cases - -Use cases for typical situations you may encounter. - -[#uc-add-toc] -=== Add a TOC - -Add a TOC to a document written without one, so that it's easier to navigate and use. - -**** -Sometimes documents are written without TOCs for good reason - they may be part of a larger system, or automatically generated. -What ever the reason, you can add one using the {project-name}. -**** - -*Problem: A document is not written with a TOC* - -It's long. It's hard to navigate. - -*Solution: Use {project-name} to add a TOC* - -Add the `toc` setting depending on your need below: - -* For all documents viewed, use a xref:custom-attributes-option.adoc[common attribute]: - - toc=left - -* For the current document, use a <>: - - ?toc=left - -* If editing the document, use this AsciiDoc in the header: - - :toc: left - -[NOTE] -==== -To remove a TOC that's already there use `toc` followed by an exclamation mark (`!`). - -* Custom attribute: `toc!` -* Query parameter: `?toc!` -==== - - -[[uc-simplify-toc]] -=== Simplify the TOC - -Reduce the TOC heading levels for a simplified view of the document. - -**** -Some documents have so many headings and sections that there is too much detail, even in the TOC. -While that may be OK for the final purpose, for your purpose you want to change your view of it. -**** - -*Problem: The number of section levels and headings are many* - -A simple view of the TOC is needed to understand the document. - -*Solution: Use the viewer to reduce the TOC heading levels* - -Attribute `toclevels` controls the section levels that are included in the TOC, from 1 to 7. -Add the `toclevels` setting depending on your need below: - -* For all documents viewed, use a xref:custom-attributes-option.adoc[common attribute]: - - toclevels=1 - -* For the current document, use a <>: - - ?toclevels=1 - -* If editing the document, use this AsciiDoc in the header: - - :toclevels: 1 - -TIP: To see more detail in the TOC, increase the `toclevels` value. - -=== Add a simplified TOC - -To combine the use cases of <> and <> you can set both `toc` and `toclevels` at the same time: - -* For all documents viewed, set these as xref:custom-attributes-option.adoc[common attributes]: - - toc=left toclevels=1 - -* For the current document, use these <>: - - ?toc=left&toclevels=1 - -* If editing the document, use this AsciiDoc in the header: - - :toc: left - :toclevels: 1 - - -=== Minimal effort writing - -Create and write an AsciiDoc quickly using the {project-name} to apply your most commonly used settings. - -**** -When taking notes, you just want to write and not add for example settings for the TOC, nice admonition icons and other items. -**** - -*Objective: Just write, leaving other settings until later if at all* - -Use the features of {project-name} to save time. - -*Solution: Put commonly used attributes into the xref:custom-attributes-option.adoc[]* - -For all documents viewed, set this xref:custom-attributes-option.adoc[custom attributes option string]: - - toc=left icons=font experimental source-highlighter=highlight.js - -The above Custom attributes options string set the equivalent AsciiDoc attributes below: - -.AsciiDoc header -[,asciidoc] ----- -= -:toc: left <.> -:icons: font <.> -:experimental: <.> -:source-highlighter: highlight.js <.> ----- -<.> A left hand TOC -<.> Use Font Awesome for icons and admonition icons -<.> Enable GUI macros + -`\btn:[button]` for btn:[button] + -`\kbd:[control-A]` for kbd:[control-A] and + -`\menu:Menu[Item,...]` for select menu:Menu[Item,...] -<.> Syntax highlighting with `highlight.js` - -Congratulations, you can now have a collection of AsciiDoc notes with minimal effort, and view them with the {project-name}. +* xref:asciidoctor:migrate:markdown.adoc[Migrate from Markdown to Asciidoctor] via Asciidoctor (the generator) \ No newline at end of file diff --git a/docs/modules/ROOT/pages/quickstart.adoc b/docs/modules/ROOT/pages/quickstart.adoc new file mode 100644 index 00000000..9b9ca1ad --- /dev/null +++ b/docs/modules/ROOT/pages/quickstart.adoc @@ -0,0 +1,37 @@ += Quickstart + +To reproduce the example shown in <<example>>, do the following: + +:exfile: ex-writing-zen.adoc + +. Install the {project-name} using the xref:install.adoc[] page +. Create `{exfile}` from the text below or xref:attachment${exfile}[download] it. ++ +.ex-writing-zen.adoc +----- +include::attachment${exfile}[] +----- + +. Open `{exfile}` in your browser. You may either: + +* Open it by pressing kbd:[Control,O] +* Drag and drop `{exfile}` onto your browser +* Double-click `{exfile}` ++ +NOTE: For double-click to work, you may need to change your computer settings to associate `.adoc` with your web browser. + +. Try different features with the following: + +.. Toggle the {project-name} activation by clicking its extension icon in the browser bar. ++ +You'll see the AsciiDoc behind the rendered HTML page. +.. Change the xref:theme-stylesheet-option.adoc[] and reload. +.. Change the Theme/Stylesheet using a query parameter. +Add `stylesheet=github` to the end of the URL. +.. Edit the AsciiDoc file and save. +Observe it update. +.. Add `toc=left` to xref:custom-attributes-option.adoc[], and reload. + +. Next steps ++ +After the above, you may like to try the exercise in the xref:diagrams-extension-option.adoc[]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/use-cases.adoc b/docs/modules/ROOT/pages/use-cases.adoc new file mode 100644 index 00000000..85a67118 --- /dev/null +++ b/docs/modules/ROOT/pages/use-cases.adoc @@ -0,0 +1,133 @@ +[#use-cases] += Use cases + +Use cases for typical situations you may encounter. + +[#uc-add-toc] +== Add a TOC + +Add a TOC to a document written without one, so that it's easier to navigate and use. + +**** +Sometimes documents are written without TOCs for good reason - they may be part of a larger system, or automatically generated. +What ever the reason, you can add one using the {project-name}. +**** + +*Problem: A document is not written with a TOC* + +It's long. It's hard to navigate. + +*Solution: Use {project-name} to add a TOC* + +Add the `toc` setting depending on your need below: + +* For all documents viewed, use a xref:custom-attributes-option.adoc[common attribute]: + + toc=left + +* For the current document, use a <<url-query-parameters,query parameter>>: + + ?toc=left + +* If editing the document, use this AsciiDoc in the header: + + :toc: left + +[NOTE] +==== +To remove a TOC that's already there use `toc` followed by an exclamation mark (`!`). + +* Custom attribute: `toc!` +* Query parameter: `?toc!` +==== + + +[[uc-simplify-toc]] +== Simplify the TOC + +Reduce the TOC heading levels for a simplified view of the document. + +**** +Some documents have so many headings and sections that there is too much detail, even in the TOC. +While that may be OK for the final purpose, for your purpose you want to change your view of it. +**** + +*Problem: The number of section levels and headings are many* + +A simple view of the TOC is needed to understand the document. + +*Solution: Use the viewer to reduce the TOC heading levels* + +Attribute `toclevels` controls the section levels that are included in the TOC, from 1 to 7. +Add the `toclevels` setting depending on your need below: + +* For all documents viewed, use a xref:custom-attributes-option.adoc[common attribute]: + + toclevels=1 + +* For the current document, use a <<url-query-parameters,query parameter>>: + + ?toclevels=1 + +* If editing the document, use this AsciiDoc in the header: + + :toclevels: 1 + +TIP: To see more detail in the TOC, increase the `toclevels` value. + +== Add a simplified TOC + +To combine the use cases of <<uc-add-toc>> and <<uc-simplify-toc>> you can set both `toc` and `toclevels` at the same time: + +* For all documents viewed, set these as xref:custom-attributes-option.adoc[common attributes]: + + toc=left toclevels=1 + +* For the current document, use these <<url-query-parameters,query parameters>>: + + ?toc=left&toclevels=1 + +* If editing the document, use this AsciiDoc in the header: + + :toc: left + :toclevels: 1 + + +== Minimal effort writing + +Create and write an AsciiDoc quickly using the {project-name} to apply your most commonly used settings. + +**** +When taking notes, you just want to write and not add for example settings for the TOC, nice admonition icons and other items. +**** + +*Objective: Just write, leaving other settings until later if at all* + +Use the features of {project-name} to save time. + +*Solution: Put commonly used attributes into the xref:custom-attributes-option.adoc[]* + +For all documents viewed, set this xref:custom-attributes-option.adoc[custom attributes option string]: + + toc=left icons=font experimental source-highlighter=highlight.js + +The above Custom attributes options string set the equivalent AsciiDoc attributes below: + +.AsciiDoc header +[,asciidoc] +---- += <title> +:toc: left <.> +:icons: font <.> +:experimental: <.> +:source-highlighter: highlight.js <.> +---- +<.> A left hand TOC +<.> Use Font Awesome for icons and admonition icons +<.> Enable GUI macros + +`\btn:[button]` for btn:[button] + +`\kbd:[control-A]` for kbd:[control-A] and + +`\menu:Menu[Item,...]` for select menu:Menu[Item,...] +<.> Syntax highlighting with `highlight.js` + +Congratulations, you can now have a collection of AsciiDoc notes with minimal effort, and view them with the {project-name}. \ No newline at end of file