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] another way to do it new another bullet but here we do astrid asterisk it will automatically put it as a child of our first bullet if i want to go another tear down you just add another bullet one go even further down i gotta make sure that they're in order but as you keep going they just keep adding blocks after that but over here it's still readable now we can also change our bullets so you could still use asterisk or you could do hyphen uh and it's a nice title and then if i do dash you see it repeats the process so you can use dashes or asterisks all right that's unordered lists we want to do ordered list title alright so if we do an ordered list you do dot number so if you just keep adding dots space and text it'll just keep adding the next incrementation if you want to do a sub child and then it will do numbers we do three we'll do letters we do four you'll now do capital and then if you do five you'll do capital i's still fairly readable another way you can do it you can actually combine let's say we want to do letters so if we wanted letters just start out with letters and then if i wanted to add children to that now you can add indentations here or not uh if you add indentations it just kind of makes it cleaner to read over here in the text now if we wanted to combine letters and numbers so we could do child we could do single dot which then changes us back to a number we could also use numbers now on we can mix them you could also do definitions copy this in to make it cleaner definitions look like this so you have your term and then definition so to do that you use two colons the text two colons and then it converts it to a definition and if you want crowds just add another colon here we have definition for one add another colon pushes it over push it over again and we want to add definitions within definitions that use semicolons get colons treats it as if they are straight definitions so one two but if i change it to semicolons it now staggers them now we could also change how we read the definitions so right now they're stacked so we have term and then the definition on the next line if we lead with the bracket horizontal it puts our definition right next to our term and if we change our label here um the horizontal has to be at the left-hand side you could also do question and answers this is good if you're doing like a quiz site if you want to break your list you can do something like this list if we want to do number item one and one two three four but this was actually gonna be one and two again what we do here we can create a block and as you can see it restarted the numbering you can nest all kinds of formatting so here we have our title doing a bullet we're doing a number block and a bullet again non-literal another block over here very you clean also do tables here's an example of a table three columns five rows and our text looks like this so you have your bracket options headers and footers i have a header my headers are going to be bolded and then i use pipes and i use equal signs and i use pipes to separate my columns very clean easy to read it did the same thing for comma delimited data so you can take csv data and say 15 for each column you can format csv the width is 60 columns are four you can set your frame you can set different things like top bot grid none with the grid i also believe you can read cvs files in that's kind of cool you want to add some additional formatting so options header columns here's some additional formatting and then you can also do multi-cell wristband of the melting multi-cell row column span two three four eight duration average notes if you want to do two columns or two rows plus two or dot two come over here making two rows that's just an example of how to use the ascii doc now there are other things you can use with ascii doc you can use things like ascii doctor which allow you to install this in docker and it's basically another translator you can take ascii doc html5 doc book or more this is good if you have ruby so you can use it as a ruby plugin and there's essentially a plugin for ascii doc for almost every language what's kind of cool is and what turned me on to asciidoc was spring is actually now using it with their rest packages i go to a few projects so if you do spring rest stock it actually auto-generates ascii doc syntax with ascii doctor so instead of it looking all nasty with your old java docs actually makes a very clean api for your code i know we started early um that's kind of it an overview does anyone have any questions michael um this is just a comment this is really cool and it really piqued my interest um uh as a short backstory of him was in the middle of writing my thesis in word and and so it was a docx and um we had a number of equations that we were trying to uh format in word and word started crashing on me because uh i guess it just wasn't a stable implementation of all those equations and so this uh uh this tool would have helped me convert that docx to a tech which was the format that we uh ended up using a tech file uh then latex to uh uh render the document um it's really cool so i i like the presentation just for that and um and also i saw a as i was listening i was doing a uh a search there is a um a pan doc i don't know if you ran across that in your uh preparations uh pandoc which can convert to and from this ascii doc format um uh i again just started tinkering with it and it's really powerful as well so that's a great presentation yeah there's a lot you can do with it uh there's pac-man uh like for example i forgot to mention the plugins so if you go to the ascii doc page and here are all the different plugins so you can actually convert it to like a wordpress uh like gman and you mentioned math so if you come down here to the filters uh you can do block diagrams for diagram filter uh i think there's a yeah there's a graphics one and i think there's even a math one so this probably would have been perfect for what you were trying to do absolutely it would have i agree but that's the thing that's why i brought this up because i saw this at java one a couple years ago but i couldn't remember the name of it and now that spring has incorporated it within their rest docs i was like ah that's it because i actually write most of my documentation in notepad plus plus or just me kind of a superficial text editor and most of my documentation looks like this or is close to this and i was like that's kind of cool i could easily just tweak how i do my shorthand and then i can convert this document into an html or a pdf document yeah yeah that's that's uh that's really powerful um and i again uh that can dock tool as well um i'm the lazy guy that wants to use a lot less shorthand and just open up a docx file or a word document and compile some things like that it can convert your docx to uh an ascii doc that's a and that then that markup can all persist across whatever format you need it to yep and here's another one so this is another theme called power man which is a condensed version i'm with you it's really cool any other questions bring none with that we'll wrap things up we appreciate your time and if you'd like to discuss any of these topics further just reach out to us we're on info developer.com we're also on twitter at developerner we're still on facebook at facebook.com developmenter and you can reach us on our contact us page at developernerd.com our videos are also on vimeo and we're also on youtube so come check out our blogs and our videos and as always our goal is making every developer better have a great day [Music] you
Transcript Segments
[Music]
another way to do it
new
another bullet
but here we do
astrid asterisk
it will automatically put it as a child
of our first bullet
if i want to go another tear down you
just add another bullet
one go even further down
i gotta make sure that they're in order
but as you keep going
they just keep adding blocks after that
but over here it's still readable
now we can also change our bullets
so you could still use asterisk
or you could do
hyphen
uh
and
it's a nice title
and then if i do dash
you see it repeats the process
so you can use dashes or asterisks
all right that's unordered lists
we want to do ordered list
title
alright so if we do an ordered list
you do dot
number
so if you just keep adding dots
space and text it'll just keep adding
the next
incrementation
if you want to do a sub child
and then it will do numbers
we do three
we'll do letters
we do four
you'll now do capital
and then if you do five
you'll do capital
i's
still fairly readable
another way you can do it
you can actually combine
let's say we want to do letters
so if we wanted letters just start out
with letters
and then if i wanted
to add children to that
now you can add indentations here
or not
uh if you add indentations it just kind
of makes it cleaner to read over here in
the text
now if we wanted to combine
letters and numbers
so we could do child we could do
single dot
which then changes us back to a number
we could also use numbers
now on we can mix them
you could also do definitions
copy this in to make it cleaner
definitions look like this
so you have your term
and then
definition
so to do that you use two colons
the text two colons and then it converts
it to a definition
and if you want
crowds
just add another
colon
here we
have definition for one
add another colon pushes it over
push it over again
and we want to add
definitions within definitions
that use semicolons
get colons
treats it as if they are
straight definitions so one two
but if i change it to semicolons it now
staggers them
now we could also change how we read
the definitions
so right now they're stacked
so we have term
and then the definition on the next line
if we
lead
with the bracket horizontal
it puts our definition
right next to our term
and if we change our label
here um
the horizontal has to be at the
left-hand side
you could also do question and answers
this is good if you're doing
like a quiz site
if you want to break your list
you can do something like this
list
if we want to do number
item one
and one
two three four
but this was actually gonna be one and
two again
what we do here we can
create a block
and as you can see it restarted the
numbering
you can nest all kinds of formatting
so here we have our title
doing a bullet we're doing a number
block
and a bullet again
non-literal
another block
over here
very
you clean also do tables
here's an example of a table
three columns
five rows
and our text looks like this
so you have your bracket
options headers and footers
i have a header
my headers are going to be bolded
and then i use pipes
and i use equal signs
and i use pipes to separate
my
columns
very clean easy to read
it did the same thing for comma
delimited data
so you can take csv data
and say 15 for each column
you can format csv
the width is 60
columns are four
you can set your frame
you can set different things like top
bot
grid none with the grid
i also believe you can read
cvs files in
that's kind of cool
you want to add some additional
formatting
so options
header
columns
here's some additional formatting
and then you can also do multi-cell
wristband
of the melting multi-cell
row column span
two three four eight duration average
notes
if you want to do two columns
or two rows plus two or dot two
come over here
making
two rows
that's just an example of how to use the
ascii doc
now there are other things you can use
with ascii doc
you can use things like
ascii doctor
which allow you to install
this in
docker
and it's basically another translator
you can take ascii doc
html5
doc book or more
this is good if you have ruby
so you can use it as a ruby plugin
and there's essentially a plugin for
ascii doc
for almost every language
what's kind of cool is and what turned
me on to asciidoc
was
spring is actually now using it
with their rest packages
i go to a few projects
so if you do spring rest stock
it actually
auto-generates ascii doc
syntax with ascii doctor
so instead of it looking all nasty with
your old java docs
actually makes a very clean api for your
code
i know we started early um
that's kind of
it an overview
does anyone have any questions
michael um this is just a comment this
is really cool and it really piqued my
interest um uh as a short backstory of
him
was in the middle of writing my thesis
in word
and and so it was a docx and um
we had a number of equations that we
were trying to uh format in word and
word started crashing on me because uh i
guess it just wasn't a stable
implementation
of all those equations and so
this uh uh
this tool would have helped me convert
that docx to
a tech which was the format that we uh
ended up using a tech file uh then latex
to uh
uh render the document um it's really
cool so i i like the presentation just
for that and um and also i saw a
as i was listening i was doing a uh
a search there is a um a pan doc i don't
know if you ran across that in your uh
preparations uh pandoc which can convert
to and from this ascii doc format
um
uh i
again just started tinkering with it and
it's really powerful as well so that's a
great presentation
yeah there's a lot you can do with it uh
there's pac-man
uh like for example i forgot to mention
the plugins so if you go to the ascii
doc page
and here are all the different plugins
so you can actually convert it to like a
wordpress
uh like gman and you mentioned math
so if you come down here to the filters
uh you can do block diagrams for diagram
filter
uh i think there's a yeah there's a
graphics one
and i think there's even a math one
so this probably would have been perfect
for what you were trying to do
absolutely it would have i agree
but that's the thing that's why i
brought this up because
i saw this at java one a couple years
ago
but i couldn't remember the name of it
and
now that spring has incorporated it
within their rest docs i was like ah
that's it
because i actually write most of my
documentation in notepad plus plus
or just me
kind of a superficial text editor
and most of my documentation
looks like this or is close to this and
i was like that's kind of cool i could
easily just
tweak how i do my shorthand
and then i can convert this document
into
an html or a pdf document
yeah yeah
that's that's uh that's really powerful
um and i again uh
that can dock tool as well
um
i'm the lazy guy that wants to use a lot
less shorthand and
just open up a docx file or a word
document and compile some things like
that
it can convert your docx to uh an ascii
doc that's a and that then that markup
can all
persist across whatever format you need
it to
yep and here's another one so this is
another theme called power man
which is a
condensed version
i'm with you
it's really cool
any other questions
bring none
with that we'll wrap things up we
appreciate your time and if you'd like
to discuss any of these topics further
just reach out to us
we're on info developer.com
we're also on
twitter at developerner we're still on
facebook at facebook.com
developmenter
and you can reach us on our contact us
page at developernerd.com
our videos are also on vimeo
and we're also on
youtube
so
come check out our blogs and our videos
and
as always our goal is making every
developer better have a great day
[Music]
you