= asciidoc - plainish text for fancy output :author: der.hans :title: asciidoc: plainish text for fancy output :date: 2017Jul13 @ PLUG :copyright: 2017 der.hans --- CC BY-SA 4.0 unported :max-width: 45em :website: https://www.LuftHans.com/ :source-highlighter: pygments == intro page an approximate^1^ history of documentation formats ^1^ and mostly inaccurate == itb in the beginning...there was ASCII text^1^ ^1^ and it was *good* == a-zA-Z+ then in the 1980s^1^ other countries got electricity ^1^ that's an estimate == take that Americans learned there are other languages and invented Perl as revenge == Perl begat regexen Perl gave us regular expressions^1^ so we could find out what cartoon swearing means ^1^ history as it should be == dots in English dots only go on the letter i^1^, but suddenly people started dotting round vowels ^1^ and the commas at the end of a line in Perl == #!/bin/notenglish document headers were introduced to warn people of the coming barbarism^1^ ^1^ binary, proprietary documentation formats are truly barbaric == caffienated documentation documentation got hyper and we all got nesting instinct^1^ ^1^ [source,html] ----

unicorns

---- == ! a \ we spent hours explaining that a / is not a \^1^ ^1^ luckily backslasher movies never happened == the human is the computer we built hand-crafted^1^ documentation snowflakes ^1^ tech documentation as user interface design :( == *bzzzzt* We can fix this!!! == the birth of markup simplified formatting pretending to be other formatting == when simple isn't simple markup begat templates^1^ ^1^ smarty pants templates to hide PHP complexity == this is not the Highlander you remember there can never be only one^1^ ^1^ there is no singular form of the word standards == snowflakes galore y+aml^1^ ^1^ y-y-y-y-y-y-y-y-y-y-y-y-yaml == flip not up == support for Maryland README.md == exec table MarkDown requires tools^1^ to create a Table of Contents ^1^ sonic screwdrivers do not work on (wooden) tables == welcome to the promised Doc AsciiDoc to the rescue == ASCII bunny _____________________ < What's up AsciiDoc? > --------------------- \ \ \ \ /\ ( ) .( o ). // == ToC // :toc: == What is asciidoc? Plain text markup with a variety of output formats. == Some output formats * html * JavaScript-based web presentation ( you're soaking in it ) * DocBook * man page * ODF * ePub * PDF == Where is it supported? * your computer :) * GitHub and GitHub wiki * GitLab * Drupal, WordPress, ikiwiki * many text editors == What about MarkDown? * no internal Table of Contents :( * no includes * email block-quoting, but not in email * triple-back-quoting??? * some other minor nits ** part of the home game :) == Key use cases for me * Systems and Procedures Documentation * Wiki with WebUI in GitLab and GitHub * Text-based markup ** greppable ** automation ** standard revision control * DR * include files == Document Conversion * asciidoc ** asciidoc --backend=slidy file.adoc * pandoc * asciidoctor == Getting Graphic * ditaa * Graphviz dot * PlantUML == Syntax simple with complex possibilities == Headers ---- = document title ( level 0 ) == title level 1 === title level 2 == title level 1 === title level 2 ==== title level 3 ---- == paragraphs ---- text with a blank line before and after another paragraph and another ---- text with a blank line before and after another paragraph and another == unordered lists ---- * Dr. Seuss ** thing1 ** thing2 * cars ** VW thing * Addams Family ** thing ---- * Dr. Seuss ** thing1 ** thing2 * cars ** VW thing * Addams Family ** thing == ordered list ---- . one . two . three .. three and a third .. three and two thirds . four ---- . one . two . three .. three and a third .. three and two thirds . four == checklist ---- * [*] check * [] cash * [] credit ---- * [*] check * [] cash * [] credit == links ---- http://AsciiDoc.org/[AsciiDoc] ---- http://AsciiDoc.org/[AsciiDoc] == source code Use four dashes, ----, alone on lines to start and end the block [source,bash] ---- function find_ssh_agent() { if [ ! -S "$SSH_AUTH_SOCK" ] ; then # Find the your first SSH socket file if you don't already have one local pS=$( ls /tmp/ssh-*/agent.* | head -1 ) # Verify potential_SAS is a socket, has correct uid and gid and also the dir has correct uid and gid if [ -S "$pS" -a -O "$pS" -a -G "$pS" -a -O "${pS%/*}" -a -G "${pS%/*}" ] ; then export SSH_AUTH_SOCK="$pS" fi fi } # Find an SSH_AUTH_SOCK, call ssh. Use '\ssh' to get ssh w/o the helper fx() alias ssh="find_ssh_agent; echo $SSH_AUTH_SOCK; ssh-add -l; ssh" ---- == issues Not all AsciiDoc features are supported by all backends == Resources * http://asciidoc.org/[http://asciidoc.org/ - AsciiDoc site] * http://asciidoc.org/asciidoc.txt[http://asciidoc.org/asciidoc.txt AsciiDoc documentation in AsciiDoc] * http://asciidoctor.org/[http://asciidoctor.org/ Ruby AsciiDoc processor with good AsciiDoc documentation] * http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ AsciiDoc Syntax Quick Reference] * https://github.com/powerman/asciidoc-cheatsheet/wiki[https://github.com/powerman/asciidoc-cheatsheet/wiki GitHub Wiki AsciiDoc cheatsheet]