Detailed Notes
We always need to document our code and processes. That does not mean we always do. Ascii Doc is a tool that can make it easy for us to quickly create documentation that looks good and in many formats.
Ascii Doc Link: https://asciidoc-py.github.io
Transcript Text
[Music] today we are going to be talking about ascii docs which is a text editor technique that we can use to simplify our documentation so what is ascii docs well ascii docs is a text document format for writing notes documentation articles books and so on it's just a way of simplifying like a text editor where your text is readable in pretty much any format like if you're using a text editor if you're using vimeo uh navigate bim nano uh basically from any command line editor you can read the documentation cleanly and what's cool about this is ascii docs allows you to convert this text into essentially any format so you can do html pdf xhtml xml so basically you write something that's clean easy to read and then you can essentially translate it to any type of format that you want and ascii docs is also highly configurable it has plugins it has themes you can also inject code you can inject html i mean you can do so much with it and so here's an example of four different flavors of the same document so down here in the right hand corner is a clean man uh text written in ascii code above it is a the same uh text in pdf apache fop uh to the top left is your standard pdf file so if you actually try to read the text of pdf this is what you would see and then in the lower left is how this text would look in html so in order to translate this clean text into html you have to have all these different tags pdf you have to have all the different pdf syntax uh pdf fob it see it's a little cleaner to read but you still have a lot more syntax in here than you would just in a plain text document so this is kind of the beauty of using ascii doc it lets you write a very clean readable text document that you can read from any essentially command line text editor whatever but you can convert this document to any format that you need for the web uh or even just for straight up documentation so if you want to create like a pdf book or a manual that you could publish with your software you could take the ascii doc here and then just run it through the compiler and it would generate the man file it would generate the pdf file or the ebook file that you could then publish all right so that's it for the slides for now so let's actually get out here this is going to be more of a hands-on today all right so out here let's start by going to the ascii homepage so asciidocs.org is the base homepage for ascii docs it's got a fairly straightforward installation section here down at the bottom it's installed from a github repository uh which by the way i found out that asking docs is kind of also the de facto documentation format that github is using so if you want to install on windows your setups here it's pretty straightforward um linux is also pretty straightforward mac has a little uh issue right now so homebrew has kind of been disabled from the pseudo level so if you want to install ascii docs on a mac you have to actually configure the user rights to the folders for the installation the other thing it's going to want is it's also going to require python 3 for your installation so that you can actually run python to convert the documentation so for instance uh we have to test the installation so we have a doc asciidoc.txt i've got this installed already here development deducts citation so here we have an ascii.txt and as you can see it's just a straight text document but using the ascii doc format and we'll walk through what each of these syntaxes mean here but just if i scroll through this you can see that this is a very readable document it's very clean uh i mean and you can you can understand it now if i close this document here and i run the converter so if i ran this python ascii docs pi against the text file i've already done so here we would see the html version of that same text file so now we have all of our links and we have all the documentation this is the power of ascii docs so ascii docs can look very clean from a ascii perspective from a command line perspective or text document but then you can convert it to any format that you need and then once you convert it you can then deploy it with your application either be an e-reader file or you can deploy the html straight to your website all right so i'm going to jump out to this other url here uh spartan.github.io asky.box now you can install this yourself but there's a couple different ones of these online so you don't really need to do the setup yourself this is just kind of a text editor that you can type and type your ascii code here and you'll see the output over here so the first thing i want to show you is so if we look at the ascii.txt we have this header information here drop this in here so this website currently ignores this they're running a different theme but you can put in a header information this way and it will have like author information email different types of format text documentation icons numbering and website uh i believe this guy is running a ruby implementation so the other way to display your header is with the underlines or we can do there we are dashes we have one two three four five six seven eight nine ten eleven twelve so twelve dashes gets you a title of your document and the little block underneath it so that everything you type is now going to be inside of our block we could put some text in there with some markup so here on the left there is no reason to prefer this particular markup it has all the features footers and so on and on the right it is kind of cut off right now this is using the uh pac-man uh i believe this has like uh ruby and pac-man for this particular editor there's some things we can do so if you're thinking like html we'll leave our title here and let's put in a header so headers in html are the typical h1 through h5 well in ascii docs you can represent the levels or your headers like so we have the dashes two three four five six seven so seven dashes is equivalent of h1 as you can see you start with your header you follow it with the dashes and it's translated to a header anything after the dash is it's just plain text actually what you have to do is you have to make sure that you have the dash under each character that represents your title or your headers so here we have example one then you have your different levels so this is h2 this is represented by squiggles if shift backwards hyphen and you have your carrots and then pluses for level four we have our examples so one dashes two wiggles three are carrots h4 or plus and we can also represent these the same way with equals so if i do equal equal i can then do level one which is our h1 if i do three now in h2 this is kind of a cleaner way of doing your headers or your different levels level three as you can see over here it's fairly readable it translates really well right so if we just want text you can just start typing text creates any text underneath like a a p tag in html so it's like p so there's no enters you have to put actual breaks if you want a title inside of your documentation you start with a period and then you just do title then once you put some text underneath it you see that the title pops up paragraph next now if i want to do a literal paragraph you have to start with a space and you'll see it puts a block around it and then what you do here is everything you type it reads the enter key so this is now traded like a three let's pre-format it then now you can do all your indentation anytime you put a space in between it will put a block for those horizontal lines some other things that are cool with using ascii you can do tip now it becomes a tip block if you apply formatting you can change icons so this could be like an information icon a warning icon you can also do things like important caution warnings yep text a warning block and a caution block now this guy doesn't have the icons installed but like i said this could be uh just like a little notepad or an information icon uh this could be like an alert exclamation point uh this could be like a red warning stop sign uh caution the other thing you can do with these is you can also essentially they're a a block so every time you keep typing it just keeps adding it it keeps expanding you can format that another way you could also do a note so if we want to change this up here with our title but then also make this a note do this all caps and now it creates a note block and you can also change your note to be an icon as well you could also do things like code if you give it a title you put in the source so this is like the code tag in html and then you can actually put in your code if you installed the theme or the plugin for the code the code will actually be color coded as if it was in an editor [Music] you
Transcript Segments
[Music]
today we are going to be talking about
ascii docs
which is a
text editor
technique that we can use to simplify
our documentation
so what is ascii docs well ascii docs is
a
text document format for writing notes
documentation
articles
books and so on it's just a way
of simplifying like a text editor
where
your text is readable in pretty much any
format like if you're using a text
editor if you're using vimeo
uh navigate bim nano
uh
basically from any command line editor
you can read the documentation cleanly
and what's cool about this is
ascii docs allows you to convert this
text into essentially any format so you
can do html pdf
xhtml xml
so basically you write something that's
clean easy to read
and then you can essentially translate
it to any type of format that you want
and ascii docs is also highly
configurable
it has plugins it has themes
you can also inject code you can inject
html i mean you can do so much with it
and so here's an example of
four different flavors of the same
document
so down here in the right hand corner is
a
clean man
uh
text written in ascii code
above it is a the same uh text in pdf
apache fop
uh to the top left is your standard pdf
file so if you actually try to read the
text of pdf this is what you would see
and then in the lower left is
how this text would look in html
so in order to translate this clean text
into html you have to have all these
different tags pdf you have to have all
the different pdf syntax
uh pdf fob it see it's a little cleaner
to read but
you still have a lot more syntax in here
than you would just in a plain text
document
so this is kind of the beauty
of using ascii doc
it lets you write a very clean readable
text document that you can read from
any essentially command line
text editor whatever
but you can convert this document to any
format that you need for the web
uh or even just for straight up
documentation
so if you want to create like a pdf book
or a manual that you could publish with
your software
you could take the ascii doc here and
then just
run it through the compiler and it would
generate the man file it would generate
the pdf file
or the ebook file that you could then
publish
all right so that's it for the slides
for now so let's actually get out here
this is going to be more of a hands-on
today
all right so out here let's start by
going to the ascii homepage
so
asciidocs.org
is the base homepage for ascii docs
it's got a fairly straightforward
installation section here
down at the bottom
it's installed from a github repository
uh which by the way i found out that
asking docs is
kind of also the de facto documentation
format that
github is using
so if you want to install
on windows your setups here it's pretty
straightforward
um
linux is also pretty straightforward
mac
has a
little uh issue right now so
homebrew has kind of been disabled from
the pseudo level
so if you want to install
ascii docs on a mac you have to actually
configure
the user rights to the folders for the
installation
the other thing it's going to want is
it's also going to require python 3
for your installation so that you can
actually run python
to convert the documentation
so for instance
uh we have
to test the installation so we have a
doc asciidoc.txt
i've got this installed already
here
development
deducts
citation
so here we have an ascii.txt
and as you can see it's just a straight
text document
but using the ascii
doc format
and we'll walk through what each of
these syntaxes mean here
but just if i scroll through this you
can see that this is a very readable
document it's very clean
uh i mean and you can you can understand
it
now
if i close this document here
and i run the converter
so if i ran this python ascii docs pi
against the text file
i've already done
so here we would see
the html version of that same text file
so now we have all of our links
and we have all the documentation
this is the power of ascii docs so ascii
docs can look very clean
from a ascii perspective from a command
line perspective or text document
but then you can convert it to any
format that you need
and then once you convert it you can
then deploy it with your application
either be an e-reader file
or you can deploy the html straight to
your website
all right so i'm going to jump out to
this other url here
uh
spartan.github.io
asky.box
now you can install this yourself
but
there's a couple different ones of these
online
so you don't really need to do
the setup yourself this is just kind of
a text editor that you can type and
type your ascii code here and you'll see
the
output over here
so the first thing
i want to show you is so if we look at
the
ascii.txt
we have this header information here
drop this in here so this
website
currently ignores this they're running a
different theme
but you can put in a header information
this way
and it will have like author information
different types of format text
documentation icons numbering and
website
uh i believe this guy is running a ruby
implementation so the other way to
display your header
is
with
the underlines
or we can do
there we are dashes
we have one two three four five six
seven eight nine ten eleven twelve
so twelve dashes
gets you a title of your document
and the little block underneath it so
that everything you type is now going to
be inside of our block
we could put some text in there
with some markup
so here on the left
there is no reason to prefer
this particular markup
it has all the features footers and so
on
and on the right it
is kind of cut off right now
this is using the uh pac-man
uh i believe this has like uh ruby and
pac-man for this particular editor
there's some things we can do so
if you're thinking like html
we'll leave our
title here
and let's put in a
header
so headers in html
are the typical h1 through h5
well in
ascii docs
you can represent the levels or your
headers
like
so we have
the dashes
two three four five six seven so seven
dashes
is equivalent of
h1
as you can see you start with your
header
you follow it with the dashes
and it's translated to a header
anything after the dash is it's just
plain text
actually what you have to do is you have
to make sure that you have
the dash under each
character that represents your title or
your
headers
so here we have example one
then you have your different levels so
this is h2
this is represented by squiggles
if shift backwards hyphen
and you have your carrots and then
pluses for level four
we have our examples
so
one
dashes
two
wiggles
three
are carrots
h4
or plus
and we can also represent these
the same way with equals
so if i do equal equal
i can then do level one
which is our h1
if i do three
now in h2
this is kind of a cleaner way of doing
your headers or your
different levels
level three
as you can see over here it's fairly
readable it translates really well
right so if we just want text you can
just start typing text
creates any text underneath like a
a p tag in html so it's like p
so there's no enters you have to put
actual breaks
if you want a title
inside of your documentation
you start with a period
and then you just do
title
then once you put some text underneath
it you see that the title pops up
paragraph
next
now if i want to
do a literal paragraph
you have to start with a space
and you'll see it puts a
block around it
and then what you do here is everything
you type
it reads the enter key
so this is now traded like a
three
let's pre-format it
then now you can do all your indentation
anytime you put a space in between
it will put a block
for those horizontal lines
some other things that are cool with
using ascii
you can
do tip
now it becomes a tip block
if you apply formatting you can change
icons so this could be like an
information icon a warning icon
you can also do things like important
caution
warnings
yep text
a warning block
and a caution block now this guy
doesn't have the icons installed
but like i said this could be
uh just like a little notepad
or
an information icon
uh this could be like an alert
exclamation point
uh this could be like a red warning stop
sign
uh caution
the other thing you can do with these is
you can also
essentially they're
a a block so every time you keep typing
it just keeps adding it
it keeps expanding
you can format that
another way you could also do a note
so if we want to change this up here
with our title
but then also make this a note
do this
all caps
and now it creates a note block
and you can also change your note to be
an icon
as well
you could also do things like
code
if you give it a title
you put in the source so this is like
the code tag in html
and then you can actually put in your
code
if you installed the theme or the plugin
for the code
the code will actually be color coded as
if it was in an editor
[Music]
you