SlideShare une entreprise Scribd logo
1  sur  184
Words in Code
Pete Goodliffe
!
pete@goodliffe.net
@petegoodliffe
As software developers we do not just write
code. We write many, many words too.
!
We write documentation, comments, manuals,
specifications, technical articles, wiki
documentation, and more. Maybe even
magazine articles and books.
!
This talk discusses some practicalities of
writing well, both stylistically and practically.
We'll talk about prose, but also about the right
"geek" way of writing, the storage formats,
toolchains, and the storage of our words.
!
We'll cover:
- writing style
- what's appropriate: what to write what not to
write
- keeping track: "source control" for words
- toolchains: what toolsets to use to write and
prepare output
- markup languages vs "wysiwyg" tools
- sharing your words with non-geeks
!
At the end of this talk, you'll have a good idea
how to put together an example "document
toolchain" taking source-controlled words in a
humane markup style, and creating high-
quality
ePub and Kindle output, as well as Word-
friendly versions.
accu conference
april 2014
Pete Goodliffe
PROGRAMMER / AUTHOR / COLUMNIST /
TEACHER / CONSCIENTIOUS CODER
Words in Code
<head>
Words in Code
Words in Code
Words in Code
#1
#2
#3
recap
how / what
mechanisms for writing
writing style
available tools — a toolchain
publishing
what do i know
about this?
<< docbook
latex
framemaker
mediawiki >>
<< word
odt
text
asciidoc
(framemaker)
asciidoc >>
html
css
epub
limited time discount
http://gum.co/
becomingbetter/accu2014
word
<body>
on writing
<section>
all programmers
should do it
Thinking for Programmers
Leslie Lamport, Build 2014
what how?
what?
(do you know)
Either write something
worth reading or do
something worth writing.
!
Benjamin Franklin
how?
write furiously
read & edit
structure
submit
don’t stop the flow!
(chose a medium that doesn’t get in the way)
plan structure & direction
before you start writing
(outline, mindmap, notebook)
tidy sentences
remove vast sections
(return after days)
accu?
magazine editors are very
helpful & will work with you
good writing style
Words in Code
read
!
(a lot)
If you don't have time to read,
you don't have the time (or the
tools) to write. Simple as that.
!
Stephen King
only write when
you have
something to say
be specific
use simple words
use the active voice
(SVO)
short paragraphs
engage; be
conversational
remove
unnecessary words
keep to the point,
don’t ramble
DRY
clear sections
coherent
paragraphs target your
audience
(voicing)
The most valuable of all
talents is that of never using
two words when one will do.
!
Thomas Jefferson
&
<section>
plain text
TEX / LA
TEX
RTF
HTML
word/open office/pages/etc
docbook
lightweight markup
doxygen
ndoc
javadoc
etcdocthings
plain text
primitive // lingua franca // core unix // ebcdic, ascii, unicode
This	
  project	
  builds	
  on	
  Apple	
  Mac	
  OS	
  and	
  MS	
  Windows	
  (we	
  
build	
  on	
  Win	
  7,	
  but	
  it	
  builds	
  on	
  Win	
  8	
  as	
  well,	
  if	
  you're	
  
desperate).	
  
!
To	
  build	
  this	
  project	
  on	
  MacOS	
  you	
  need	
  to	
  install:	
  
	
  	
  	
  	
  *	
  Xcode	
  5	
  
	
  	
  	
  	
  *	
  Install	
  the	
  Xcode	
  command	
  line	
  tools	
  
	
  	
  	
  	
  *	
  cmake	
  
	
  	
  	
  	
  *	
  PackageMaker	
  (from	
  the	
  Mac	
  developer	
  auxiliary	
  
tools)	
  
!
To	
  build	
  this	
  project	
  on	
  Win32/Win64	
  you	
  need	
  to	
  install:	
  
	
  	
  	
  	
  *	
  Visual	
  Studio	
  2013	
  for	
  Windows	
  Desktop	
  
TEX
LATEX
documentclass{article}	
  
!
begin{document}	
  
!
centerline{sc	
  large	
  A	
  Simple	
  Sample	
  LaTeX	
  File}	
  
vspace{.5pc}	
  
centerline{sc	
  Stupid	
  Stuff	
  I	
  Wish	
  Someone	
  Had	
  Told	
  Me	
  Four	
  
Years	
  Ago}	
  
centerline{it	
  (Read	
  the	
  .tex	
  file	
  along	
  with	
  this	
  or	
  it	
  won't	
  	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  make	
  much	
  sense)}	
  
vspace{2pc}	
  
!
The	
  first	
  thing	
  to	
  realize	
  about	
  LaTeX	
  is	
  that	
  it	
  is	
  not	
  
``WYSIWYG''.	
  	
  
In	
  other	
  words,	
  it	
  isn't	
  a	
  word	
  processor;	
  what	
  you	
  type	
  into	
  
your	
  	
  
.tex	
  file	
  is	
  not	
  what	
  you'll	
  see	
  in	
  your	
  .dvi	
  file.	
  	
  For	
  example,	
  	
  
LaTeX	
  will	
  	
  	
  	
  	
  	
  completely	
  	
  	
  	
  	
  ignore	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  extra	
  
spaces	
  	
  	
  	
  within	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  a	
  line	
  of	
  your	
  .tex	
  
file.	
  
Pressing	
  return	
  
in	
  	
  
the	
  	
  
middle	
  	
  
of
documentclass{article}	
  
!
begin{document}	
  
!
centerline{sc	
  large	
  A	
  Simple	
  Sample	
  LaTeX	
  File}	
  
vspace{.5pc}	
  
centerline{sc	
  Stupid	
  Stuff	
  I	
  Wish	
  Someone	
  Had	
  Told	
  Me	
  Four	
  
Years	
  Ago}	
  
centerline{it	
  (Read	
  the	
  .tex	
  file	
  along	
  with	
  this	
  or	
  it	
  won't	
  	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  make	
  much	
  sense)}	
  
vspace{2pc}	
  
!
The	
  first	
  thing	
  to	
  realize	
  about	
  LaTeX	
  is	
  that	
  it	
  is	
  not	
  
``WYSIWYG''.	
  	
  
In	
  other	
  words,	
  it	
  isn't	
  a	
  word	
  processor;	
  what	
  you	
  type	
  into	
  
your	
  	
  
.tex	
  file	
  is	
  not	
  what	
  you'll	
  see	
  in	
  your	
  .dvi	
  file.	
  	
  For	
  example,	
  	
  
LaTeX	
  will	
  	
  	
  	
  	
  	
  completely	
  	
  	
  	
  	
  ignore	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  extra	
  
spaces	
  	
  	
  	
  within	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  a	
  line	
  of	
  your	
  .tex	
  
file.	
  
Pressing	
  return	
  
in	
  	
  
the	
  	
  
middle	
  	
  
of
RTF
{rtf1ansiansicpg1252cocoartf1265cocoasubrtf190	
  
{fonttblf0fswissfcharset0	
  ArialMT;f1fromanfcharset0	
  
TimesNewRomanPSMT;f2ftechfcharset77	
  Symbol;	
  
}	
  
{colortbl;red255green255blue255;red191green191blue191;}	
  
{*listtable{listlisttemplateid1listhybrid{listlevel
levelnfc23levelnfcn23leveljc0leveljcn0levelfollow0levelstartat1
levelspace360levelindent0{*levelmarker	
  {disc}}{leveltext
leveltemplateid1'01uc0u8226	
  ;}{levelnumbers;}
fi-­‐360li720lin720	
  }{listname	
  ;}listid1}}	
  
{*listoverridetable{listoverridelistid1listoverridecount0ls1}}	
  
{info	
  
{title	
  This	
  is	
  a	
  test	
  RTF}	
  
{author	
  Nate}}vieww12540viewh16140viewkind1viewscale80	
  
deftab720	
  
pardpardeftab720ri0sb240sa60	
  
!
f0bfs32	
  cf0	
  This	
  is	
  a	
  test	
  RTF	
  
pardpardeftab720ri0	
  
!
f1b0fs24	
  cf0	
  Hi!	
  I'92m	
  a	
  test	
  file.	
  This	
  is	
  some	
  	
  
b	
  bold	
  
b0	
  	
  text,	
  and	
  some	
  	
  
i	
  italic	
  
i0	
  	
  text,	
  as	
  well	
  as	
  some	
  ul	
  underlineulnone	
  	
  text.	
  And	
  a	
  bit	
  of	
  
hidden	
  text.	
  So	
  we'92re	
  going	
  to	
  end	
  this	
  paragraph	
  here	
  and	
  go	
  on	
  
to	
  a	
  nice	
  little	
  list:
HTML
!
<div	
  class="sect1	
  chapter">	
  
<h2	
  id="_care_about_the_code">Care	
  About	
  The	
  Code</h2>	
  
<div	
  class="sectionbody">	
  
<div	
  class="quoteblock">	
  
<div	
  class="content">From	
  caring	
  comes	
  courage.</div>	
  
<div	
  class="attribution">	
  
&#8212;	
  Lao	
  Tzu	
  
</div></div>	
  
<div	
  class="paragraph"><p><!-­‐-­‐	
  ix	
  myindex	
  <Caring>	
  -­‐-­‐><a	
  id="ix0"></a>	
  
It	
  doesn&#8217;t	
  take	
  Sherlock	
  Holmes	
  to	
  work	
  out	
  that	
  good	
  programmers	
  
write	
  
good	
  code.	
  Bad	
  programmers&#8230;	
  don&#8217;t.	
  They	
  produce	
  elephantine	
  
monstrosities	
  that	
  the	
  rest	
  of	
  us	
  have	
  to	
  clean	
  up.	
  You	
  want	
  to	
  write	
  
the	
  good	
  stuff,	
  right?	
  You	
  want	
  to	
  be	
  a	
  good	
  programmer.</p></div>	
  
<div	
  class="paragraph"><p>Good	
  code	
  doesn&#8217;t	
  pop	
  out	
  of	
  thin	
  air.	
  
It	
  isn&#8217;t	
  something	
  that	
  happens	
  
by	
  luck	
  when	
  the	
  planets	
  align.	
  To	
  get	
  good	
  code	
  you	
  have	
  to	
  work	
  at	
  it.	
  
Hard.	
  And	
  you&#8217;ll	
  only	
  get	
  good	
  code	
  if	
  you	
  actually	
  <em>care</em>	
  
about	
  good	
  
code.</p></div>	
  
docbook
<chapter	
  id="CuttingCode_Architecture_Chapter">	
  
<chapterinfo><releaseinfo>$Id:	
  Chapter.xml	
  2850	
  2006-­‐08-­‐29	
  22:54:54Z	
  pete	
  $</
releaseinfo></chapterinfo>	
  
<title>Software	
  Architecture</title>	
  
<subtitle>Laying	
  the	
  Foundations	
  of	
  Software	
  Design</subtitle>	
  
!
<indexterm	
  significance="preferred"	
  class="startofrange"><primary>Architecture</
primary></indexterm>	
  
!
<graphic	
  srccredit="Pete	
  Goodliffe"	
  fileref="$DOCROOT/Chapters/Architecture/
Picture.eps"	
  />	
  
!
<highlights>	
  
<itemizedlist	
  spacing="compact">	
  
	
  	
  	
  	
  <listitem><para>What	
  is	
  software	
  architecture?</para></listitem>	
  
	
  	
  	
  	
  <listitem><para>How	
  is	
  software	
  architecture	
  different	
  from	
  code	
  design?</
para></listitem>	
  
</itemizedlist>	
  
</highlights>	
  
!
<!-­‐-­‐	
  =====================================================================	
  -­‐-­‐>	
  
<epigraph>	
  
<attribution>Philip	
  Johnson</attribution>	
  
<para>Architecture	
  is	
  the	
  art	
  of	
  how	
  to	
  waste	
  space.</para>	
  
</epigraph>	
  
!
<para>Go	
  into	
  a	
  city.	
  Stand	
  in	
  the	
  middle	
  of	
  it.	
  Look	
  around.	
  Unless	
  you've	
  picked	
  
an	
  unusual	
  place,	
  you	
  will	
  be	
  surrounded	
  by	
  a	
  large	
  number	
  of	
  buildings	
  of	
  varying	
  
ages	
  and	
  styles	
  of	
  construction.	
  Some	
  fit	
  into	
  their	
  surroundings	
  sympathetically.	
  
Others	
  look	
  totally	
  out	
  of	
  place.	
  Some	
  are	
  aesthetically	
  pleasing	
  and	
  seem	
  well	
  
proportioned.	
  Others	
  are	
  downright	
  ugly.	
  Some	
  will	
  still	
  be	
  there	
  in	
  100	
  years'	
  
time.	
  Many	
  will	
  not.</para>	
  
wysiwyg
!
word/open office/pages/etc
wysiwyg
!
(inwyw)
styles
maths
version control
file format control
collaboration
including source code
multiple outputs
your document structure
(this sucks)
initial version
add chapter 2
update introduction
fix typo in chapter 1
add dancing leprechauns
version control log
diff it
!
go on, i dare you
one file has all of the things
all text content
all graphics
all style information
all structure
all indexing
(you wouldn’t do that with your source code)
Words in Code
my_book.thing
introduction.thing
chapter1.thing
chapter2.thing
graphics
graphic.png
my_awesome_book my ideal world
there is a better way
lightweight markup
!
markdown
asciidoc
various wiki syntaxes
(mediawiki, PmWiki)
textile
reStructuredText
lightweight markup
!
markdown
asciidoc
various wiki syntaxes
(mediawiki, PmWiki)
textile
reStructuredText
humane
markdown
The overriding design goal for Markdown’s formatting
syntax is to make it as readable as possible.
!
A Markdown-formatted document should be
publishable as-is, as plain text, without looking like it’s
been marked up with tags or formatting instructions.
!
The single biggest source of inspiration for
Markdown’s syntax is the format of plain text e-mail.
— John Gruber, Creator of Markdown
simple (istic)
can’t cover all requirements
fragmentation
markdown
markdown asciidoc
leanpub o’reilly
github github
blog platforms++ blog platforms
markdown asciidoc
limited
restricted toolchain
docbook equivalent
richer toolchain
asciidoc
<section>
proxy for docbook
!
(but it’s humane)
Output
!
HTML
(HTML 4, XHTML 1.1, HTML 5)
DocBook
PDF (fop, dblatex, custom)
ePub
man
ODF
slides deck.js, dzslides
…and more
!
readable
concise
comprehensive
extensible
mature, high-quality
produces beautiful output
=	
  AsciiDoc	
  Example	
  
Pete	
  Goodliffe	
  <pete@goodliffe.net>	
  
!
An	
  optional	
  preface.	
  
!
NOTE:	
  This	
  is	
  a	
  specially	
  formatted	
  note.	
  
!
==	
  First	
  Section	
  
!
*	
  item	
  1	
  
*	
  item	
  2	
  
!
[source,ruby]	
  
puts	
  "Hello,	
  World!"	
  
asciidoc example
<?xml	
  version="1.0"	
  encoding="UTF-­‐8"?>	
  
<!DOCTYPE	
  book	
  PUBLIC	
  "-­‐//OASIS//DTD	
  DocBook	
  XML	
  V4.5//EN"	
  
	
  	
  	
  	
  "http://www.oasis-­‐open.org/docbook/xml/4.5/docbookx.dtd">	
  
<book	
  lang="en">	
  
	
  	
  	
  	
  <bookinfo>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <title>Asciidoc	
  example</title>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <date>2014-­‐04-­‐12</date>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <author>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <firstname>Pete</firstname>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <surname>Goodliffe</surname>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <email>pete@goodliffe.net</email>	
  
	
  	
  	
  	
  	
  	
  	
  	
  </author>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <authorinitials>PG</authorinitials>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <revhistory>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <revision>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <revnumber>1.0</revnumber>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <date>2014-­‐04-­‐12</date>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <authorinitials>PG</authorinitials>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  </revision>	
  
	
  	
  	
  	
  	
  	
  	
  	
  </revhistory>	
  
	
  	
  	
  	
  </bookinfo>
docbook equivalent
!
	
  	
  	
  	
  <preface>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <simpara>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  An	
  optional	
  preface.	
  
	
  	
  	
  	
  	
  	
  	
  	
  </simpara>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <note>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <simpara>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  This	
  is	
  a	
  specially	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  formatted	
  note.	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  </simpara>	
  
	
  	
  	
  	
  	
  	
  	
  	
  </note>	
  
	
  	
  	
  	
  </preface>	
  
docbook equivalent
!
	
  	
  	
  	
  <chapter	
  id="_first_section">	
  
	
  	
  	
  	
  	
  	
  	
  	
  <title>First	
  section</title>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <simpara>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  Document	
  sections	
  start	
  at	
  level	
  1	
  and	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  can	
  nest	
  up	
  to	
  four	
  levels	
  deep.	
  
	
  	
  	
  	
  	
  	
  	
  	
  </simpara>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <itemizedlist>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <listitem>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <simpara>Item	
  1</simpara>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  </listitem>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <listitem>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <simpara>Item	
  2</simpara>	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  </listitem>	
  
	
  	
  	
  	
  	
  	
  	
  	
  </itemizedlist>	
  
docbook equivalent
!
!
!
!
!
!
	
  	
  	
  	
  <programlisting>	
  
	
  	
  	
  	
  	
  	
  	
  	
  <emphasis	
  role=“bold">puts</emphasis>	
  "Hello,	
  World!"	
  
	
  	
  	
  	
  </programlisting>	
  
	
  	
  </chapter>	
  
</book>	
  
!
!
!
!
!
!
docbook equivalent
#	
  Asciidoc	
  example	
  
!
An	
  optional	
  preface.	
  
!
>	
  **Note**	
  
>	
  
>	
  This	
  is	
  a	
  specially	
  formatted	
  note.	
  
!
##	
  First	
  section	
  
!
Document	
  sections	
  start	
  at	
  level	
  1	
  and	
  can	
  nest	
  up	
  to	
  four	
  
levels	
  deep.	
  
!
*	
  Item	
  1	
  
*	
  Item	
  2	
  
!
~~~~~~~~	
  
puts	
  "Hello,	
  World!”	
  
~~~~~~~~
markdown equivalent
asciidoc syntax
paragraphs
Paragraphs	
  don't	
  require	
  any	
  special	
  markup	
  
in	
  AsciiDoc.	
  A	
  paragraph	
  is	
  just	
  one	
  or	
  more	
  
lines	
  of	
  consecutive	
  text.	
  
!
To	
  begin	
  a	
  new	
  paragraph,	
  separate	
  it	
  by	
  at	
  
least	
  one	
  blank	
  line.
Paragraphs don't require any special markup in AsciiDoc.
A paragraph is just one or more lines of consecutive text.
!
To begin a new paragraph, separate it by at least one
blank line.
headings
underline
Title	
  (Level	
  0)	
  
===============	
  
!
Level	
  1	
  
-­‐-­‐-­‐-­‐-­‐-­‐-­‐	
  
!
Level	
  2	
  
~~~~~~~	
  
!
Level	
  3	
  
^^^^^^^	
  
!
Level	
  4	
  
+++++++	
  
headings
symmetric
=	
  Title	
  (Level	
  0)	
  =	
  
!
==	
  Level	
  1	
  ==	
  
!
===	
  Level	
  2	
  ===	
  
!
====	
  Level	
  3	
  ====	
  
!
=====	
  Level	
  4	
  =====
headings
prefix
=	
  Title	
  (Level	
  0)	
  
!
==	
  Level	
  1	
  
!
===	
  Level	
  2	
  
!
====	
  Level	
  3	
  
!
=====	
  Level	
  4
text “styling”
This	
  paragraph	
  contains	
  'emphasised',	
  
*strong*,	
  `monospaced`	
  text.	
  
You	
  can	
  style	
  le**tt**ers	
  in	
  words.
This paragraph contains emphasised, strong,
monospaced	
  text. You can style letters in words.
text “styling”
This	
  is	
  text	
  is	
  _italic_.	
  
!
This	
  is	
  inline	
  +source	
  code+.
This text is italic.
!
This is inline source	
  code.
text “styling”
That	
  can	
  apply	
  wi++th++in	
  words,	
  too.	
  
Helpfully.	
  
!
Don’t	
  talk	
  about	
  C++	
  too	
  much	
  or	
  C++	
  
will	
  get	
  annoying.
That can apply within words, too. Helpfully.
!
Don’t talk about C	
  too	
  much	
  or	
  C will get
annoying.
shucks
C+{empty}+
C++
text “styling”
Super	
  script	
  and	
  subscript	
  are	
  easy.	
  
x*x	
  can	
  be	
  written	
  as	
  x^2	
  and	
  you	
  
swim	
  in	
  H~2~O.
Super script and subscript are easy.
x*x can be written as x2 and you swim in H2O.
text “styling”
We	
  break	
  at	
  the	
  end	
  of	
  this	
  line	
  +	
  
to	
  keep	
  the	
  text	
  from	
  overflowing.	
  +	
  
(It’s	
  a	
  space	
  then	
  +)
We break at the end of this line
to keep the text from overflowing.
(It’s a space then +)
“smart” quotes
`single	
  smart	
  quotes'	
  
!
``double	
  smart	
  quotes''
‘single smart quotes’
!
“double smart quotes"
smart text replacements
(C)	
  (R)	
  (TM)	
  -­‐-­‐	
  ...	
  -­‐>	
  =>	
  	
  
apostrophes	
  (auto-­‐smart)	
  
and	
  more
© ® ™ — … →
literal paragraphs
A	
  normal	
  paragraph.	
  
!
	
  A	
  literal	
  paragraph,	
  begins	
  with	
  at	
  least	
  
	
  one	
  space.	
  It	
  is	
  rendered	
  in	
  a	
  monospace	
  
	
  font	
  and	
  line	
  breaks	
  are	
  preserved.	
  
!
Another	
  normal	
  paragraph.
A normal paragraph.
!
A	
  literal	
  paragraph,	
  begins	
  with	
  at	
  least	
  
one	
  space.	
  It	
  is	
  rendered	
  in	
  a	
  monospace	
  
font	
  and	
  line	
  breaks	
  are	
  preserved.	
  
!
Another normal paragraph.
footnotes
Footnotes	
  are	
  simple	
  to	
  add.footnote:
[They	
  can	
  be	
  named,	
  and	
  have	
  multiple	
  
references.]
Footnotes are simple to add.1
!
—
1. They can be named, and have multiple references.
captions
.Caption	
  
Any	
  element	
  can	
  be	
  preceded	
  by	
  a	
  
caption:	
  paragraphs,	
  blocks,	
  images,	
  
and	
  the	
  like.
Caption
Any element can be preceded by a caption:
paragraphs, blocks, images, and the like.
literal blocks
....	
  
Renders	
  as	
  pre-­‐formatted,	
  monospaced	
  
text	
  
....
!
Renders	
  as	
  pre-­‐formatted,	
  monospaced	
  
text
code blocks
basic
.Optional	
  caption	
  
-­‐-­‐-­‐-­‐	
  
public	
  interface	
  Document	
  {}	
  
-­‐-­‐-­‐-­‐
!
Listing 1: Optional caption
public interface Document {}!
code blocks
syntax colouring
[source,c#]	
  
.C#	
  (syntax	
  coloured)	
  
-­‐-­‐-­‐-­‐	
  
public	
  interface	
  Document	
  {}	
  
-­‐-­‐-­‐-­‐
!
Listing 1: C# (syntax coloured)
public interface Document {}!
code blocks
with callouts
-­‐-­‐-­‐-­‐	
  
public	
  interface	
  Document	
  <1>	
  
{	
  
	
   	
  ...	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  <2>	
  
}	
  
-­‐-­‐-­‐-­‐	
  
<1>	
  Interface	
  name	
  
<2>	
  Gubbins	
  goes	
  here
source highlighting
in the box, if you use
in-built backends
!
coderay, highlightjs, prettify, pygments
:source-­‐highlighter:	
  pygments
sidebar blocks
.Optional	
  caption	
  
****	
  
This	
  is	
  a	
  sidebar.	
  
****
Optional caption
This is a sidebar.
quote blocks
epigraphs
[quote,	
  Albert	
  Einstein]	
  
____	
  
Two	
  things	
  are	
  infinite:	
  the	
  universe	
  and	
  
human	
  stupidity;	
  and	
  I'm	
  not	
  sure	
  about	
  the	
  
the	
  universe.	
  
____
Two things are infinite: the universe and human
stupidity; and I'm not sure about the the universe.
— Albert Einstein
quote blocks
single-line
[quote,	
  Persian	
  Proverb]	
  
Thinking	
  well	
  is	
  wise;	
  planning	
  well,	
  
wiser;	
  doing	
  well,	
  wisest	
  and	
  best	
  
of	
  all.
Thinking well is wise; planning well, wiser;
doing well, wisest and best of all.
— Persian Proverb
passthrough blocks
++++	
  
<p>	
  
Content	
  in	
  a	
  passthrough	
  block	
  is	
  
passed	
  to	
  the	
  output	
  unprocessed.	
  
That	
  means	
  you	
  can	
  include	
  raw	
  HTML,	
  
XML,	
  marine	
  life,	
  celestial	
  bodies,	
  
etc.	
  
</p>	
  
++++
unordered lists #1
*	
  apple	
  
*	
  orange	
  
**	
  tangerine	
  
**	
  satsuma	
  
*	
  lemon	
  
*	
  lime
• apple
• orange
• tangerine
• satsuma
• lemon
• lime
unordered lists #2
*	
  apple	
  
*	
  orange	
  
	
  	
  *	
  tangerine	
  
	
  	
  *	
  satsuma	
  
*	
  lemon	
  
*	
  lime
• apple
• orange
• tangerine
• satsuma
• lemon
• lime
ordered lists
1.	
  one	
  
2.	
  two	
  
	
  A.	
  two	
  a	
  
	
  B.	
  two	
  b	
  
3.	
  three
1. one
2. two
A. two a
B. two b
3. three
ordered lists
implicit numbering
.	
  one	
  
.	
  two	
  
..	
  two	
  a	
  
..	
  two	
  b	
  
.	
  three
1. one
2. two
A. two a
B. two b
3. three
definition lists
single-line
first	
  term::	
  definition	
  of	
  first	
  term	
  
section	
  term::	
  definition	
  of	
  second	
  
term
first term
definition of first term
!
section term
definition of second term
definition lists
multi-line
first	
  term::	
  
definition	
  of	
  first	
  term	
  
section	
  term::	
  
definition	
  of	
  second	
  term
first term
definition of first term
!
section term
definition of second term
links
http://asciidoc.org.	
  
!
Read	
  about	
  the	
  http://asciidoc.org[AsciiDoc	
  Project].	
  
Note	
  the	
  full-­‐stop	
  handles	
  correctly.	
  Hurrah!	
  
!
http://asciidoc.org.
!
Read about the AsciiDoc Project. Note the full-stop
handles correctly. Hurrah!
cross references
[[anchor]]Internal	
  link	
  anchor	
  here.	
  
!
Go	
  to	
  <<anchor,internal	
  link>>.	
  
Internal link anchor here.
!
Go to internal link.
links
!
pete@goodliffe.net	
  
!
Mail	
  mailto:pete@goodliffe.net[Pete	
  Goodliffe]	
  
!
irc://chat.freenode.net/#accu	
  
!
pete@goodliffe.net
!
Mail Pete Goodliffe
!
irc://chat.freenode.net/#accu
images
Inline	
  
image:images/image.png[Alt	
  text]	
  
!
Block	
  
image::images/image.png[Alt	
  text]	
  
!
.Block	
  with	
  caption	
  
image::images/image.png[Alt	
  text]
admonitions
NOTE:	
  A	
  single	
  line	
  note.	
  
!
[NOTE]	
  
Or	
  this	
  as	
  an	
  alternative.	
  
!
[NOTE]	
  
====	
  
Or	
  this	
  as	
  an	
  alternative	
  
that	
  can	
  span	
  multiple	
  blocks,	
  and	
  even	
  include	
  
* lists	
  
* and	
  other	
  things	
  
====
NOTE: A single line note
!
NOTE: Or this as an alternative.
admonitions
TIP:
NOTE:
IMPORTANT:
WARNING:
CAUTION:
comments
This	
  is	
  in	
  the	
  document.	
  
//	
  This	
  line	
  has	
  been	
  removed	
  
!
You	
  can	
  throw	
  a	
  processor	
  switch	
  to	
  
conditionally	
  include	
  comments.
This is in the document.
!
You can throw a processor switch to conditionally
include comments.
comment blocks
You	
  can	
  also	
  have	
  multi-­‐line	
  comments…	
  in	
  a	
  block!	
  
!
////	
  
A	
  multi-­‐line	
  comment.	
  
!
Notice	
  it's	
  a	
  delimited	
  block.	
  
////
You can also have multi-line comments… in a block!
tables
.Table	
  Title	
  
|===	
  
|Name	
  of	
  Col	
  1	
  |Name	
  of	
  Col	
  2	
  |Name	
  of	
  Col	
  3	
  	
  
!
|Cell	
  in	
  column	
  1,	
  row	
  1	
  
|Cell	
  in	
  column	
  2,	
  row	
  1	
  
|Cell	
  in	
  column	
  3,	
  row	
  1	
  
!
|Cell	
  in	
  column	
  1,	
  row	
  2	
  
|Cell	
  in	
  column	
  2,	
  row	
  2	
  
|Cell	
  in	
  column	
  3,	
  row	
  2	
  
|===	
  
tables
!
!
.Table	
  Title	
  
|===	
  
|Name	
  of	
  Col	
  1	
  |Name	
  of	
  Col	
  2	
  |Name	
  of	
  Col	
  3	
  	
  
!
|column	
  1,	
  row	
  1	
  |	
  col	
  2	
  |	
  col	
  3	
  
|column	
  2,	
  row	
  2	
  |	
  col	
  2	
  |	
  col	
  3	
  
|column	
  3,	
  row	
  3	
  |	
  col	
  2	
  |	
  col	
  3	
  
|===	
  
!
!
attributes and substitutions
:homepage:	
  http://www.goodliffe.net	
  
!
Check	
  out	
  {homepage}[my	
  homepage].	
  
Check out my homepage.
attributes and conditionals
:experimental:	
  yes	
  
!
Normal	
  text	
  
!
ifdef::experimental[]	
  
This	
  text	
  is	
  only	
  included	
  if	
  experimental	
  is	
  defined.	
  
endif::experimental[]
Normal text
!
This text is only included if experimental is defined.
or… asciidoc -a experimental=yes …
table of contents
:toc:	
  
//	
  that	
  “enables”	
  TOC	
  generation;	
  
//	
  it	
  will	
  be	
  inserted	
  in	
  the	
  right	
  
//	
  place	
  magically
Table of Contents
Chapter 1 … … … … … … … … Page 1
Chapter 2 … … … … … … … … Page 10
Chapter 3 … … … … … … … … Page 23
bibliography
‘Code	
  Craft'	
  <<codecraft>>	
  is	
  a	
  marvellous	
  book.	
  
!
[bibliography]	
  
-­‐	
  [[[codecraft]]]	
  Pete	
  Goodliffe.	
  ‘Code	
  Craft:	
  
	
  	
  The	
  Practice	
  of	
  Writing	
  Excellent	
  Code'.	
  	
  
	
  	
  No	
  Starch	
  Press.	
  2005.
Code Craft [codecraft] is a marvellous book.
!
Bibliography
[codecraft]
Pete Goodliffe.
‘Code Craft: The Practive of Writing Excellent Code’.
No Start Press. 2005.
includes
include::chapter.asciidoc[]
includes
!
!
!
!
!
:a-­‐base—source:	
  https://www.goodliffe.net/
example	
  
!
include::{a-­‐base—source}/file.asciidoc[]	
  
!
!
!
!
includes allow for
a sane file structure,
and a beautiful top-level file
Becoming	
  a	
  Better	
  Programmer	
  
============================	
  
:author:	
  	
  	
  	
  Pete	
  Goodliffe	
  
:email:	
  	
  	
  	
  	
  pete@goodliffe.net	
  
:date:	
  	
  	
  	
  	
  	
  2014-­‐04-­‐01	
  
:revision:	
  	
  0.00	
  
:doctype:	
  	
  	
  book	
  
:lang:	
  	
  	
  	
  	
  	
  en	
  
!
:toc:	
  
:toc-­‐placement:	
  manual	
  
:toc-­‐title:	
  
:toclevels:	
  1	
  
:numbered!:	
  
!
////////////////////////////////////////////////////////////////////////////////	
  
This	
  is	
  an	
  example	
  of	
  the	
  source	
  for	
  my	
  new	
  book.	
  
This	
  is	
  the	
  book.asciidoc	
  file.	
  It	
  has	
  no	
  content	
  itself,	
  just	
  preamble	
  
and	
  includes	
  for	
  other	
  files.	
  
////////////////////////////////////////////////////////////////////////////////	
  
!
//	
  Frontmatter	
  
include::frontmatter/legal.asciidoc[]	
  
include::frontmatter/dedication.asciidoc[]	
  
include::frontmatter/author.asciidoc[]	
  
include::frontmatter/intro.asciidoc[]	
  
!
//	
  Chapters	
  
include::chapters/CareAboutTheCode.asciidoc[]	
  
include::chapters/PeoplePower.asciidoc[]	
  
!
//	
  ...	
  and	
  so	
  on	
  ...
book.asciidoc
introduction.asciidoc
chapter1.asciidoc
chapter2.asciidoc
graphics
graphic.png
my_awesome_book achievement
unlocked
custom styling (“roles”)
for when you really, absolutely, have to
(i.e. not often)
The	
  following	
  [custom_role]#word#	
  is	
  
given	
  a	
  custom	
  role.
The following <span class=“custom_role”>word</
span> is given a custom role.
block metadata
.Gettysburg	
  Address	
  
[[gettysburg]]	
  
[quote,	
  Abraham	
  Lincoln,	
  Soldiers'	
  National	
  
Cemetery	
  Dedication]	
  
____	
  
Four	
  score	
  and	
  seven	
  years	
  ago	
  our	
  fathers	
  
brought	
  forth	
  
on	
  this	
  continent	
  a	
  new	
  nation...	
  
!
Now	
  we	
  are	
  engaged	
  in	
  a	
  great	
  civil	
  war,	
  testing	
  
whether	
  
that	
  nation,	
  or	
  any	
  nation	
  so	
  conceived	
  and	
  so	
  
dedicated,	
  
can	
  long	
  endure.	
  ...	
  
____
title
id
style (role)
named attributes
asciidoc toolchains
!
asciidoc (python)
asciidoctor (ruby)
pandoc (haskell)
asciidoc.py <- the tool
-b <xhtml11, epub, pdf> <- backend
-o output.html <- output
source.asciidoc <- input
practical asciidoc
don’t over-style for visual appearance
(visuals are determined by backend)
!
use structure to emphasise
and highlight your text
don’t try to force your text
into a different structure
!
use headings, subheadings, unordered lists, lists,
admonitions, definition lists
!
captions are not subheads
bold is not a subhead
definition lists are for lists, not for subheads
indexing
index terms
indexterm:[Tigers,Big	
  cats]	
  
(((Tigers,Big	
  cats)))
Index
Tigers,
A silly index entry, 134
Big cats, 10
In literature, 12
index terms
This	
  is	
  a	
  book	
  all	
  about	
  ((tigers)).	
  
!
indexterm2:[tigers]
This is a book all about tigers.
!
Index
Tigers, 10
for docbook
(and epub)
!
the index toolchain just works
flexndex
!
https://github.com/elextr/flexndex
$(FLEXNDEX_VERSION): $(ASCIIDOC)
cp -r src $(FLEXNDEX_VERSION)
find $(FLEXNDEX_VERSION) -name "*.asciidoc"
| xargs
sed -i flextmp
-e 's/(((/=[/g'
-e 's/)))/]=/g'
the pre-process munge
asciidoc.conf
# "Standard" flexndex kinda macros, to set up
# ix:myindex[term] (where "term" is an entry in the index "myindex")
# ixhere::myindex[] (the index "myindex" is generated here)
(?su)(?P<name>ix):(?P<target>S*?)([(?P<attrlist>.*?)])=
(?u)^(?P<name>ixhere)::(?P<target>S*?)([(?P<attrlist>.*?)])$=#
!
[ix-inlinemacro]
<!-- ix {target} <{attrlist}> -->
!
[ixhere-blockmacro]
<!-- ixhere {target} <{attrlist=}> —>
!
# Pete's preferred cunning:
# =[term]= defines an index term here, in the hardcoded index
# "myindex"
# (still use ixhere:myindex[] to generate that index)
=[(?P<attrlist>.*?)]==ixsingle
!
[ixsingle-inlinemacro]
<!-- ix myindex <{attrlist}> -->
flexndex.py
$(HTML_OUT)
$(HTML_OUT).flexndex
--config $(FLEXNDEX_CONF)
flexndexery
flexndex.conf
!
(mostly just stuff)
default_style=simple-grouped
!
[styles.simple-grouped.xhtml11]
!
prefix=<div class="flexndex-index">
postfix=</div>
!
levels.1.text_internal =
levels.1.link_last = <p><!--(1.link_last)-->{ixterm},{sp}<a href="#ix{ixtgt}" class="notext">{ixterm}</a>
levels.1.text_last = <p><!--(1.text_last)-->{ixterm}
levels.1.multi_target = <!--(1.multi_target)-->,{sp}<a href="#ix{ixtgt}" class="notext">{ixtext}</a>
!
levels.2.text_internal =
levels.2.link_last = <p style="text-indent:{ixindent}em;">&nbsp;&nbsp;&nbsp;<!--(levels.2.link_last)--
>{ixterm},{sp}<a href="#ix{ixtgt}" class="notext">{ixterm}</a>
levels.2.text_last = <p style="text-indent:{ixindent}em;">&nbsp;&nbsp;&nbsp;<!--(levels.2.text_last)--
>{ixterm}
levels.2.multi_target = <!--(levels.2.multi_target)-->,{sp}<a href="#ix{ixtgt}" class="notext">{ixtext}</a>
!
entry_start=<!--(entry_start)-->
entry_end=<!--(entry_end)--></p>{nl}
complete=e
<div class="sect1">
<h2 id="_index">Index</h2>
<div class="sectionbody">
<div class=“flexndex-index">
<!—(entry_start)-->
<p>
<!--(1.text_last)-->API<!--(1.multi_target)-->,
<a href="#ix158" class=“notext">API</a><!--(1.multi_target)-->,
<a href="#ix144" class=“notext">API</a><!--(entry_end)-->
</p>
html output
pdf tooling
asciidoc.py
-b pdf
-d book
-a <some attributes>
-o $(HTML_OUT)
$(BOOK_SOURCE)
asciidoc
html
pdf
css
asciidoc
html
pdf
pdf css
epub
epub css
all you have to do
now is learn CSS
PrinceXML
http://www.princexml.com
!
WeasyPrint
http://weasyprint.org
!
xhtml2pdf
http://www.xhtml2pdf.com
!
wkhtmltopdf
http://wkhtmltopdf.org
final pdf steps
!
pdftk
“If PDF is electronic paper, then pdftk is an
electronic staple-remover, hole-punch, binder,
secret-decoder-ring, and X-Ray-glasses.”
pdftk
!
update pdf metadata (creator, title, author, keywords)
cut pages out
merge pages (e.g. add cover)
adjust page bookmarks
mobi tooling
for the kindle
epub
mobi
kindlegen
kindlegen
book.epub
-c2
-verbose
-o book.mobi
*************************************************************
Amazon kindlegen(MAC OSX) V2.8 build 0208-797bf75
A command line e-book compiler
Copyright Amazon.com and its Affiliates 2013
*************************************************************
!Info:I9007:option: -c2: Kindle Huffdic compression
Info(prcgen):I1047: Added metadata dc:Title "Becoming a Better Programmer"
Info(prcgen):I1047: Added metadata dc:Date "2014-03-26"
Info(prcgen):I1047: Added metadata dc:Creator "Pete Goodliffe"
Info(prcgen):I1052: Kindle support cover images but does not support cover HTML. Hence using the cover image specified and suppressing cover HTML in content. URL: /var/folders/0t/
2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/cover.html
Info(prcgen):I1002: Parsing files 0000025
Info(cssparser):I10004: @rules other than @import, @charset and @font-face are not supported.
Warning(htmlprocessor):W28001: CSS style specified in content is not supported by Kindle readers. Removing the CSS property: 'max-width' in file: /var/folders/0t/
2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/css/epub.css
Warning(htmlprocessor):W28001: CSS style specified in content is not supported by Kindle readers. Removing the CSS property: 'max-height' in file: /var/folders/0t/
2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/css/epub.css
Warning(inputpreprocessor):W29004: Forcefully closed opened Tag: <dl>
in file: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/ix01.html line: 0000002
Warning(inputpreprocessor):W29004: Forcefully closed opened Tag: <dd>
in file: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/ix01.html line: 0000002
Warning(inputpreprocessor):W29010: Tag rejected due to being used in unauthorized scope: <dt>
in file: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/ix01.html line: 0000002
Warning(inputpreprocessor):W29010: Tag rejected due to being used in unauthorized scope: <dd>
in file: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/ix01.html line: 0000002
Info(prcgen):I1016: Building enhanced PRC file
Info(prcgen):I1015: Building PRC file
Info(prcgen):I1006: Resolving hyperlinks
Info(prcgen):I1049: Building table of content URL: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/toc.ncx
Info(pagemap):I8000: No Page map found in the book
Info(prcgen):I1045: Computing UNICODE ranges used in the book
Info(prcgen):I1046: Found UNICODE range: Basic Latin [20..7E]
Info(prcgen):I1046: Found UNICODE range: Latin-1 Supplement [A0..FF]
Info(prcgen):I1046: Found UNICODE range: General Punctuation - Windows 1252 [2018..201A]
Info(prcgen):I1046: Found UNICODE range: Letter-like Symbols [2100..214F]
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000001
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000002
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000004
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000008
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000016
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000032
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000064
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000128
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000256
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000442
Info(prcgen/compress):I4002: Compression pass 0000001
Info(prcgen/compress):I4002: Compression pass 0000002
Info(prcgen/compress):I4002: Compression pass 0000003
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 41.63%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000062574 bytes 000005159 entries
Info(prcgen/compress):I4002: Compression pass 0000004
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 36.19%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000042590 bytes 000003796 entries
Info(prcgen/compress):I4002: Compression pass 0000005
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 34.86%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000036228 bytes 000003033 entries
Info(prcgen/compress):I4002: Compression pass 0000006
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 33.98%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000030660 bytes 000002441 entries
Info(prcgen/compress):I4002: Compression pass 0000007
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 32.41%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000022576 bytes 000001967 entries
Info(prcgen/compress):I4002: Compression pass 0000008
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 32.37%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000019490 bytes 000001595 entries
Info(prcgen/compress):I4002: Compression pass 0000009
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 32.54%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000017004 bytes 000001296 entries
!
Info(prcgen/compress):I4005: Advanced compression successful (decoded and verified).
Info(prcgen):I1039: Final stats - text compressed to (in % of original size): 32.54%
Info(prcgen):I1040: The document identifier is: "Becoming_a_B-ter_Programmer"
Info(prcgen):I1041: The file format version is V6
Info(prcgen):I1031: Saving PRC file
Info(prcgen):I1032: PRC built successfully
Info(prcgen):I1007: Resolving mediaidlinks
Info(prcgen):I1011: Writing mediaidlinks
Info(prcgen):I1009: Resolving guide items
Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max).
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 45.26%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000073362 bytes 0000
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 42.31%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000059026 bytes 0000
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 38.80%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000042640 bytes 0000
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 37.97%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000035726 bytes 0000
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 37.69%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000030582 bytes 0000
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 36.61%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000022696 bytes 0000
Info(prcgen/compress):I4006: Text compressed to (in % of original size): 36.79%
Info(prcgen/compress):I4007: Compression dictionary statistics: 000019762 bytes 0000
Info(prcgen):I1039: Final stats - text compressed to (in % of original size): 36.79%
Info(prcgen):I1041: The file format version is V8
Info(prcgen):I15000: Approximate Standard Mobi Deliverable file size : 0001661KB
Info(prcgen):I15001: Approximate KF8 Deliverable file size : 0001702KB
Info(prcgen):I1036: Mobi file built successfully
Ta da!
demonstration
selling your book
<section>
leanpub
iBookstore, kindle direct publishing, kobo, B&N
scribd
!
lulu, blurb, createspace, completelynovel
!
gumroad, sellfy, selz
!
smashwords, bookbaby
!
actual factual publisher
isbns
amazon
$0-2.98 or $10.00+ 35%
$2.99-$9.99 70%
!
iBookstore
70%
!
smashwords
~60% list (85% on their store)
!
consider: delay to payment
Words in Code
Words in Code
Words in Code
dropbox
online generation
!
not in manuscript
title // subtitle // dedication
legal info // cover // etc
- - -
markdown restricted
not (very) customisable
frumpy
!
+ + +
bookstore
sample versions
pay what you like
easy update
flat fee
10% + 50¢
Words in Code
Words in Code
Words in Code
Words in Code
- - -
you’re in control
poor for sample versions
no “bookstore”
you’re doing all the marketing
!
+ + +
you’re in control
cost
analytics
website integration widget thingy
flat fee
5% + 25¢
launch strategy
drive sales
sales figures…
leanpub
118 d/l in 5w
!
gumroad
28 purchases (423 views)
62 samples (259 views)
“proper” publisher
technical edit
copy edit
write
production
first draft final draft
proposal
deal
advance
royalty
tree/electrons
about book
the market
table of contents
competitors
sample chapters
deadline!
indexing layout
cover
how rich will i get?
Writing a book is a horrible, exhausting
struggle, like a long bout with some
painful illness. One would never
undertake such a thing if one were not
driven on by some demon whom one
can neither resist nor understand.
!
George Orwell
</body>
TL;DR
(write!)
limited time discount
http://gum.co/becomingbetter/accu2014
@petegoodliffe
Thank you
for listening
Icons
Book by Pedro Lalli from The Noun Project
Document by Piotrek Chuchla from The Noun Project
Magazine by Evan Travelstead from The Noun Project
Translation by Lek Potharam from The Noun Project
Code by Darren Barone from The Noun Project
Time Out by Peacock Dream from The Noun Project
Cry by Austin Condiff from The Noun Project
Eye by Eugen Belyakoff from The Noun Project
Poop by Mourad Mokrane from The Noun Project
Folder by Hunor Csaszar from The Noun Project
Bolt by Ilsur Aptukov from The Noun Project
!
All other icons are in the public domain
Credits
Interesting references
!
AsciiDoc Syntax Quick Reference
http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
!
(Ascii)Docs with pleasure!
http://mojavelinux.github.io/decks/asciidoc-with-pleasure/#31.1
Further reading

Contenu connexe

Similaire à Words in Code

Language-agnostic data analysis workflows and reproducible research
Language-agnostic data analysis workflows and reproducible researchLanguage-agnostic data analysis workflows and reproducible research
Language-agnostic data analysis workflows and reproducible researchAndrew Lowe
 
Introduction to latex by Rouhollah Nabati
Introduction to latex by Rouhollah NabatiIntroduction to latex by Rouhollah Nabati
Introduction to latex by Rouhollah Nabatinabati
 
Javascript
JavascriptJavascript
JavascriptSushma M
 
Write effectlively in late x
Write effectlively in late xWrite effectlively in late x
Write effectlively in late xC-CORE
 
Introduction to RDoc
Introduction to RDocIntroduction to RDoc
Introduction to RDocTim Lucas
 
Introduction to RDoc
Introduction to RDocIntroduction to RDoc
Introduction to RDocTim Lucas
 
Installation guide for Latex and MOODLE
Installation guide for Latex and MOODLEInstallation guide for Latex and MOODLE
Installation guide for Latex and MOODLEabigail4894
 
Better problem solving through scripting: How to think through your #eprdctn ...
Better problem solving through scripting: How to think through your #eprdctn ...Better problem solving through scripting: How to think through your #eprdctn ...
Better problem solving through scripting: How to think through your #eprdctn ...BookNet Canada
 
HTML5 Is the Future of Book Authorship
HTML5 Is the Future of Book AuthorshipHTML5 Is the Future of Book Authorship
HTML5 Is the Future of Book AuthorshipSanders Kleinfeld
 

Similaire à Words in Code (20)

Oreilly
OreillyOreilly
Oreilly
 
14 Late X
14 Late X14 Late X
14 Late X
 
Language-agnostic data analysis workflows and reproducible research
Language-agnostic data analysis workflows and reproducible researchLanguage-agnostic data analysis workflows and reproducible research
Language-agnostic data analysis workflows and reproducible research
 
Introduction to latex by Rouhollah Nabati
Introduction to latex by Rouhollah NabatiIntroduction to latex by Rouhollah Nabati
Introduction to latex by Rouhollah Nabati
 
DSLs in JavaScript
DSLs in JavaScriptDSLs in JavaScript
DSLs in JavaScript
 
Javascript
JavascriptJavascript
Javascript
 
LaTeX for begyndere
LaTeX for begyndereLaTeX for begyndere
LaTeX for begyndere
 
LATEX.ppt
LATEX.pptLATEX.ppt
LATEX.ppt
 
xml2tex at TUG 2014
xml2tex at TUG 2014xml2tex at TUG 2014
xml2tex at TUG 2014
 
Write effectlively in late x
Write effectlively in late xWrite effectlively in late x
Write effectlively in late x
 
Introduction to RDoc
Introduction to RDocIntroduction to RDoc
Introduction to RDoc
 
Introduction to RDoc
Introduction to RDocIntroduction to RDoc
Introduction to RDoc
 
Installation guide for Latex and MOODLE
Installation guide for Latex and MOODLEInstallation guide for Latex and MOODLE
Installation guide for Latex and MOODLE
 
Better problem solving through scripting: How to think through your #eprdctn ...
Better problem solving through scripting: How to think through your #eprdctn ...Better problem solving through scripting: How to think through your #eprdctn ...
Better problem solving through scripting: How to think through your #eprdctn ...
 
Pmm05 16
Pmm05 16Pmm05 16
Pmm05 16
 
STA312 Lec1
STA312 Lec1STA312 Lec1
STA312 Lec1
 
HTML5 Is the Future of Book Authorship
HTML5 Is the Future of Book AuthorshipHTML5 Is the Future of Book Authorship
HTML5 Is the Future of Book Authorship
 
Sample
SampleSample
Sample
 
Flextable and Officer
Flextable and OfficerFlextable and Officer
Flextable and Officer
 
Learn Latex
Learn LatexLearn Latex
Learn Latex
 

Plus de Pete Goodliffe

Becoming a Better Programmer
Becoming a Better ProgrammerBecoming a Better Programmer
Becoming a Better ProgrammerPete Goodliffe
 
Running Effective Worship Rehearsals
Running Effective Worship RehearsalsRunning Effective Worship Rehearsals
Running Effective Worship RehearsalsPete Goodliffe
 
Becoming a Better Programmer (2013)
Becoming a Better Programmer (2013)Becoming a Better Programmer (2013)
Becoming a Better Programmer (2013)Pete Goodliffe
 
Version Control Done Right
Version Control Done RightVersion Control Done Right
Version Control Done RightPete Goodliffe
 
C++: The Cathedral and the Bizarre
C++: The Cathedral and the BizarreC++: The Cathedral and the Bizarre
C++: The Cathedral and the BizarrePete Goodliffe
 
iOS Development (BCS Newcastle)
iOS Development (BCS Newcastle)iOS Development (BCS Newcastle)
iOS Development (BCS Newcastle)Pete Goodliffe
 
Three Objectionable Things
Three Objectionable ThingsThree Objectionable Things
Three Objectionable ThingsPete Goodliffe
 
Coping with Complexity
Coping with ComplexityCoping with Complexity
Coping with ComplexityPete Goodliffe
 
iOS Development (BCS Edinburgh 2011-03-09)
iOS Development (BCS Edinburgh 2011-03-09)iOS Development (BCS Edinburgh 2011-03-09)
iOS Development (BCS Edinburgh 2011-03-09)Pete Goodliffe
 
Stood at the bottom of a mountain looking up
Stood at the bottom of a mountain looking upStood at the bottom of a mountain looking up
Stood at the bottom of a mountain looking upPete Goodliffe
 
iPhone development: A brief introduction
iPhone development: A brief introductioniPhone development: A brief introduction
iPhone development: A brief introductionPete Goodliffe
 
Legacy Code: Learning To Live With It
Legacy Code: Learning To Live With ItLegacy Code: Learning To Live With It
Legacy Code: Learning To Live With ItPete Goodliffe
 

Plus de Pete Goodliffe (16)

Becoming a Better Programmer
Becoming a Better ProgrammerBecoming a Better Programmer
Becoming a Better Programmer
 
Running Effective Worship Rehearsals
Running Effective Worship RehearsalsRunning Effective Worship Rehearsals
Running Effective Worship Rehearsals
 
Becoming a Better Programmer (2013)
Becoming a Better Programmer (2013)Becoming a Better Programmer (2013)
Becoming a Better Programmer (2013)
 
Design Sins
Design SinsDesign Sins
Design Sins
 
Advanced iOS
Advanced iOSAdvanced iOS
Advanced iOS
 
Version Control Done Right
Version Control Done RightVersion Control Done Right
Version Control Done Right
 
Getting Into Git
Getting Into GitGetting Into Git
Getting Into Git
 
C++: The Cathedral and the Bizarre
C++: The Cathedral and the BizarreC++: The Cathedral and the Bizarre
C++: The Cathedral and the Bizarre
 
iOS Development (BCS Newcastle)
iOS Development (BCS Newcastle)iOS Development (BCS Newcastle)
iOS Development (BCS Newcastle)
 
Three Objectionable Things
Three Objectionable ThingsThree Objectionable Things
Three Objectionable Things
 
Coping with Complexity
Coping with ComplexityCoping with Complexity
Coping with Complexity
 
Manyfestos
ManyfestosManyfestos
Manyfestos
 
iOS Development (BCS Edinburgh 2011-03-09)
iOS Development (BCS Edinburgh 2011-03-09)iOS Development (BCS Edinburgh 2011-03-09)
iOS Development (BCS Edinburgh 2011-03-09)
 
Stood at the bottom of a mountain looking up
Stood at the bottom of a mountain looking upStood at the bottom of a mountain looking up
Stood at the bottom of a mountain looking up
 
iPhone development: A brief introduction
iPhone development: A brief introductioniPhone development: A brief introduction
iPhone development: A brief introduction
 
Legacy Code: Learning To Live With It
Legacy Code: Learning To Live With ItLegacy Code: Learning To Live With It
Legacy Code: Learning To Live With It
 

Dernier

Summer training report on BUILDING CONSTRUCTION for DIPLOMA Students.pdf
Summer training report on BUILDING CONSTRUCTION for DIPLOMA Students.pdfSummer training report on BUILDING CONSTRUCTION for DIPLOMA Students.pdf
Summer training report on BUILDING CONSTRUCTION for DIPLOMA Students.pdfNaveenVerma126
 
ChatGPT-and-Generative-AI-Landscape Working of generative ai search
ChatGPT-and-Generative-AI-Landscape Working of generative ai searchChatGPT-and-Generative-AI-Landscape Working of generative ai search
ChatGPT-and-Generative-AI-Landscape Working of generative ai searchrohitcse52
 
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdfRenewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdfodunowoeminence2019
 
Basic Principle of Electrochemical Sensor
Basic Principle of  Electrochemical SensorBasic Principle of  Electrochemical Sensor
Basic Principle of Electrochemical SensorTanvir Moin
 
How to Write a Good Scientific Paper.pdf
How to Write a Good Scientific Paper.pdfHow to Write a Good Scientific Paper.pdf
How to Write a Good Scientific Paper.pdfRedhwan Qasem Shaddad
 
EPE3163_Hydro power stations_Unit2_Lect2.pptx
EPE3163_Hydro power stations_Unit2_Lect2.pptxEPE3163_Hydro power stations_Unit2_Lect2.pptx
EPE3163_Hydro power stations_Unit2_Lect2.pptxJoseeMusabyimana
 
UNIT4_ESD_wfffffggggggggggggith_ARM.pptx
UNIT4_ESD_wfffffggggggggggggith_ARM.pptxUNIT4_ESD_wfffffggggggggggggith_ARM.pptx
UNIT4_ESD_wfffffggggggggggggith_ARM.pptxrealme6igamerr
 
Phase noise transfer functions.pptx
Phase noise transfer      functions.pptxPhase noise transfer      functions.pptx
Phase noise transfer functions.pptxSaiGouthamSunkara
 
Nodal seismic construction requirements.pptx
Nodal seismic construction requirements.pptxNodal seismic construction requirements.pptx
Nodal seismic construction requirements.pptxwendy cai
 
Strategies of Urban Morphologyfor Improving Outdoor Thermal Comfort and Susta...
Strategies of Urban Morphologyfor Improving Outdoor Thermal Comfort and Susta...Strategies of Urban Morphologyfor Improving Outdoor Thermal Comfort and Susta...
Strategies of Urban Morphologyfor Improving Outdoor Thermal Comfort and Susta...amrabdallah9
 
Modelling Guide for Timber Structures - FPInnovations
Modelling Guide for Timber Structures - FPInnovationsModelling Guide for Timber Structures - FPInnovations
Modelling Guide for Timber Structures - FPInnovationsYusuf Yıldız
 
solar wireless electric vechicle charging system
solar wireless electric vechicle charging systemsolar wireless electric vechicle charging system
solar wireless electric vechicle charging systemgokuldongala
 
ASME BPVC 2023 Section I para leer y entender
ASME BPVC 2023 Section I para leer y entenderASME BPVC 2023 Section I para leer y entender
ASME BPVC 2023 Section I para leer y entenderjuancarlos286641
 
Clutches and brkesSelect any 3 position random motion out of real world and d...
Clutches and brkesSelect any 3 position random motion out of real world and d...Clutches and brkesSelect any 3 position random motion out of real world and d...
Clutches and brkesSelect any 3 position random motion out of real world and d...sahb78428
 
Landsman converter for power factor improvement
Landsman converter for power factor improvementLandsman converter for power factor improvement
Landsman converter for power factor improvementVijayMuni2
 
Transforming Process Safety Management: Challenges, Benefits, and Transition ...
Transforming Process Safety Management: Challenges, Benefits, and Transition ...Transforming Process Safety Management: Challenges, Benefits, and Transition ...
Transforming Process Safety Management: Challenges, Benefits, and Transition ...soginsider
 
Technology Features of Apollo HDD Machine, Its Technical Specification with C...
Technology Features of Apollo HDD Machine, Its Technical Specification with C...Technology Features of Apollo HDD Machine, Its Technical Specification with C...
Technology Features of Apollo HDD Machine, Its Technical Specification with C...Apollo Techno Industries Pvt Ltd
 
me3493 manufacturing technology unit 1 Part A
me3493 manufacturing technology unit 1 Part Ame3493 manufacturing technology unit 1 Part A
me3493 manufacturing technology unit 1 Part Akarthi keyan
 

Dernier (20)

Summer training report on BUILDING CONSTRUCTION for DIPLOMA Students.pdf
Summer training report on BUILDING CONSTRUCTION for DIPLOMA Students.pdfSummer training report on BUILDING CONSTRUCTION for DIPLOMA Students.pdf
Summer training report on BUILDING CONSTRUCTION for DIPLOMA Students.pdf
 
ChatGPT-and-Generative-AI-Landscape Working of generative ai search
ChatGPT-and-Generative-AI-Landscape Working of generative ai searchChatGPT-and-Generative-AI-Landscape Working of generative ai search
ChatGPT-and-Generative-AI-Landscape Working of generative ai search
 
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdfRenewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
 
Basic Principle of Electrochemical Sensor
Basic Principle of  Electrochemical SensorBasic Principle of  Electrochemical Sensor
Basic Principle of Electrochemical Sensor
 
How to Write a Good Scientific Paper.pdf
How to Write a Good Scientific Paper.pdfHow to Write a Good Scientific Paper.pdf
How to Write a Good Scientific Paper.pdf
 
EPE3163_Hydro power stations_Unit2_Lect2.pptx
EPE3163_Hydro power stations_Unit2_Lect2.pptxEPE3163_Hydro power stations_Unit2_Lect2.pptx
EPE3163_Hydro power stations_Unit2_Lect2.pptx
 
UNIT4_ESD_wfffffggggggggggggith_ARM.pptx
UNIT4_ESD_wfffffggggggggggggith_ARM.pptxUNIT4_ESD_wfffffggggggggggggith_ARM.pptx
UNIT4_ESD_wfffffggggggggggggith_ARM.pptx
 
Phase noise transfer functions.pptx
Phase noise transfer      functions.pptxPhase noise transfer      functions.pptx
Phase noise transfer functions.pptx
 
Nodal seismic construction requirements.pptx
Nodal seismic construction requirements.pptxNodal seismic construction requirements.pptx
Nodal seismic construction requirements.pptx
 
Strategies of Urban Morphologyfor Improving Outdoor Thermal Comfort and Susta...
Strategies of Urban Morphologyfor Improving Outdoor Thermal Comfort and Susta...Strategies of Urban Morphologyfor Improving Outdoor Thermal Comfort and Susta...
Strategies of Urban Morphologyfor Improving Outdoor Thermal Comfort and Susta...
 
Modelling Guide for Timber Structures - FPInnovations
Modelling Guide for Timber Structures - FPInnovationsModelling Guide for Timber Structures - FPInnovations
Modelling Guide for Timber Structures - FPInnovations
 
Lecture 2 .pptx
Lecture 2                            .pptxLecture 2                            .pptx
Lecture 2 .pptx
 
solar wireless electric vechicle charging system
solar wireless electric vechicle charging systemsolar wireless electric vechicle charging system
solar wireless electric vechicle charging system
 
ASME BPVC 2023 Section I para leer y entender
ASME BPVC 2023 Section I para leer y entenderASME BPVC 2023 Section I para leer y entender
ASME BPVC 2023 Section I para leer y entender
 
Clutches and brkesSelect any 3 position random motion out of real world and d...
Clutches and brkesSelect any 3 position random motion out of real world and d...Clutches and brkesSelect any 3 position random motion out of real world and d...
Clutches and brkesSelect any 3 position random motion out of real world and d...
 
Landsman converter for power factor improvement
Landsman converter for power factor improvementLandsman converter for power factor improvement
Landsman converter for power factor improvement
 
Transforming Process Safety Management: Challenges, Benefits, and Transition ...
Transforming Process Safety Management: Challenges, Benefits, and Transition ...Transforming Process Safety Management: Challenges, Benefits, and Transition ...
Transforming Process Safety Management: Challenges, Benefits, and Transition ...
 
計劃趕得上變化
計劃趕得上變化計劃趕得上變化
計劃趕得上變化
 
Technology Features of Apollo HDD Machine, Its Technical Specification with C...
Technology Features of Apollo HDD Machine, Its Technical Specification with C...Technology Features of Apollo HDD Machine, Its Technical Specification with C...
Technology Features of Apollo HDD Machine, Its Technical Specification with C...
 
me3493 manufacturing technology unit 1 Part A
me3493 manufacturing technology unit 1 Part Ame3493 manufacturing technology unit 1 Part A
me3493 manufacturing technology unit 1 Part A
 

Words in Code

  • 1. Words in Code Pete Goodliffe ! pete@goodliffe.net @petegoodliffe As software developers we do not just write code. We write many, many words too. ! We write documentation, comments, manuals, specifications, technical articles, wiki documentation, and more. Maybe even magazine articles and books. ! This talk discusses some practicalities of writing well, both stylistically and practically. We'll talk about prose, but also about the right "geek" way of writing, the storage formats, toolchains, and the storage of our words. ! We'll cover: - writing style - what's appropriate: what to write what not to write - keeping track: "source control" for words - toolchains: what toolsets to use to write and prepare output - markup languages vs "wysiwyg" tools - sharing your words with non-geeks ! At the end of this talk, you'll have a good idea how to put together an example "document toolchain" taking source-controlled words in a humane markup style, and creating high- quality ePub and Kindle output, as well as Word- friendly versions. accu conference april 2014
  • 2. Pete Goodliffe PROGRAMMER / AUTHOR / COLUMNIST / TEACHER / CONSCIENTIOUS CODER
  • 9. how / what mechanisms for writing writing style available tools — a toolchain publishing
  • 10. what do i know about this?
  • 14. asciidoc >> html css epub limited time discount http://gum.co/ becomingbetter/accu2014
  • 15. word
  • 19. Thinking for Programmers Leslie Lamport, Build 2014
  • 22. Either write something worth reading or do something worth writing. ! Benjamin Franklin
  • 23. how?
  • 24. write furiously read & edit structure submit don’t stop the flow! (chose a medium that doesn’t get in the way) plan structure & direction before you start writing (outline, mindmap, notebook) tidy sentences remove vast sections (return after days) accu? magazine editors are very helpful & will work with you
  • 28. If you don't have time to read, you don't have the time (or the tools) to write. Simple as that. ! Stephen King
  • 29. only write when you have something to say be specific use simple words use the active voice (SVO) short paragraphs engage; be conversational remove unnecessary words keep to the point, don’t ramble DRY clear sections coherent paragraphs target your audience (voicing)
  • 30. The most valuable of all talents is that of never using two words when one will do. ! Thomas Jefferson
  • 32. plain text TEX / LA TEX RTF HTML word/open office/pages/etc docbook lightweight markup
  • 34. plain text primitive // lingua franca // core unix // ebcdic, ascii, unicode
  • 35. This  project  builds  on  Apple  Mac  OS  and  MS  Windows  (we   build  on  Win  7,  but  it  builds  on  Win  8  as  well,  if  you're   desperate).   ! To  build  this  project  on  MacOS  you  need  to  install:          *  Xcode  5          *  Install  the  Xcode  command  line  tools          *  cmake          *  PackageMaker  (from  the  Mac  developer  auxiliary   tools)   ! To  build  this  project  on  Win32/Win64  you  need  to  install:          *  Visual  Studio  2013  for  Windows  Desktop  
  • 36. TEX
  • 37. LATEX
  • 38. documentclass{article}   ! begin{document}   ! centerline{sc  large  A  Simple  Sample  LaTeX  File}   vspace{.5pc}   centerline{sc  Stupid  Stuff  I  Wish  Someone  Had  Told  Me  Four   Years  Ago}   centerline{it  (Read  the  .tex  file  along  with  this  or  it  won't                            make  much  sense)}   vspace{2pc}   ! The  first  thing  to  realize  about  LaTeX  is  that  it  is  not   ``WYSIWYG''.     In  other  words,  it  isn't  a  word  processor;  what  you  type  into   your     .tex  file  is  not  what  you'll  see  in  your  .dvi  file.    For  example,     LaTeX  will            completely          ignore                              extra   spaces        within                                                          a  line  of  your  .tex   file.   Pressing  return   in     the     middle     of
  • 39. documentclass{article}   ! begin{document}   ! centerline{sc  large  A  Simple  Sample  LaTeX  File}   vspace{.5pc}   centerline{sc  Stupid  Stuff  I  Wish  Someone  Had  Told  Me  Four   Years  Ago}   centerline{it  (Read  the  .tex  file  along  with  this  or  it  won't                            make  much  sense)}   vspace{2pc}   ! The  first  thing  to  realize  about  LaTeX  is  that  it  is  not   ``WYSIWYG''.     In  other  words,  it  isn't  a  word  processor;  what  you  type  into   your     .tex  file  is  not  what  you'll  see  in  your  .dvi  file.    For  example,     LaTeX  will            completely          ignore                              extra   spaces        within                                                          a  line  of  your  .tex   file.   Pressing  return   in     the     middle     of
  • 40. RTF
  • 41. {rtf1ansiansicpg1252cocoartf1265cocoasubrtf190   {fonttblf0fswissfcharset0  ArialMT;f1fromanfcharset0   TimesNewRomanPSMT;f2ftechfcharset77  Symbol;   }   {colortbl;red255green255blue255;red191green191blue191;}   {*listtable{listlisttemplateid1listhybrid{listlevel levelnfc23levelnfcn23leveljc0leveljcn0levelfollow0levelstartat1 levelspace360levelindent0{*levelmarker  {disc}}{leveltext leveltemplateid1'01uc0u8226  ;}{levelnumbers;} fi-­‐360li720lin720  }{listname  ;}listid1}}   {*listoverridetable{listoverridelistid1listoverridecount0ls1}}   {info   {title  This  is  a  test  RTF}   {author  Nate}}vieww12540viewh16140viewkind1viewscale80   deftab720   pardpardeftab720ri0sb240sa60   ! f0bfs32  cf0  This  is  a  test  RTF   pardpardeftab720ri0   ! f1b0fs24  cf0  Hi!  I'92m  a  test  file.  This  is  some     b  bold   b0    text,  and  some     i  italic   i0    text,  as  well  as  some  ul  underlineulnone    text.  And  a  bit  of   hidden  text.  So  we'92re  going  to  end  this  paragraph  here  and  go  on   to  a  nice  little  list:
  • 42. HTML
  • 43. ! <div  class="sect1  chapter">   <h2  id="_care_about_the_code">Care  About  The  Code</h2>   <div  class="sectionbody">   <div  class="quoteblock">   <div  class="content">From  caring  comes  courage.</div>   <div  class="attribution">   &#8212;  Lao  Tzu   </div></div>   <div  class="paragraph"><p><!-­‐-­‐  ix  myindex  <Caring>  -­‐-­‐><a  id="ix0"></a>   It  doesn&#8217;t  take  Sherlock  Holmes  to  work  out  that  good  programmers   write   good  code.  Bad  programmers&#8230;  don&#8217;t.  They  produce  elephantine   monstrosities  that  the  rest  of  us  have  to  clean  up.  You  want  to  write   the  good  stuff,  right?  You  want  to  be  a  good  programmer.</p></div>   <div  class="paragraph"><p>Good  code  doesn&#8217;t  pop  out  of  thin  air.   It  isn&#8217;t  something  that  happens   by  luck  when  the  planets  align.  To  get  good  code  you  have  to  work  at  it.   Hard.  And  you&#8217;ll  only  get  good  code  if  you  actually  <em>care</em>   about  good   code.</p></div>  
  • 45. <chapter  id="CuttingCode_Architecture_Chapter">   <chapterinfo><releaseinfo>$Id:  Chapter.xml  2850  2006-­‐08-­‐29  22:54:54Z  pete  $</ releaseinfo></chapterinfo>   <title>Software  Architecture</title>   <subtitle>Laying  the  Foundations  of  Software  Design</subtitle>   ! <indexterm  significance="preferred"  class="startofrange"><primary>Architecture</ primary></indexterm>   ! <graphic  srccredit="Pete  Goodliffe"  fileref="$DOCROOT/Chapters/Architecture/ Picture.eps"  />   ! <highlights>   <itemizedlist  spacing="compact">          <listitem><para>What  is  software  architecture?</para></listitem>          <listitem><para>How  is  software  architecture  different  from  code  design?</ para></listitem>   </itemizedlist>   </highlights>   ! <!-­‐-­‐  =====================================================================  -­‐-­‐>   <epigraph>   <attribution>Philip  Johnson</attribution>   <para>Architecture  is  the  art  of  how  to  waste  space.</para>   </epigraph>   ! <para>Go  into  a  city.  Stand  in  the  middle  of  it.  Look  around.  Unless  you've  picked   an  unusual  place,  you  will  be  surrounded  by  a  large  number  of  buildings  of  varying   ages  and  styles  of  construction.  Some  fit  into  their  surroundings  sympathetically.   Others  look  totally  out  of  place.  Some  are  aesthetically  pleasing  and  seem  well   proportioned.  Others  are  downright  ugly.  Some  will  still  be  there  in  100  years'   time.  Many  will  not.</para>  
  • 48. styles maths version control file format control collaboration including source code multiple outputs
  • 50. initial version add chapter 2 update introduction fix typo in chapter 1 add dancing leprechauns version control log
  • 51. diff it ! go on, i dare you
  • 52. one file has all of the things
  • 53. all text content all graphics all style information all structure all indexing
  • 54. (you wouldn’t do that with your source code)
  • 57. there is a better way
  • 58. lightweight markup ! markdown asciidoc various wiki syntaxes (mediawiki, PmWiki) textile reStructuredText
  • 59. lightweight markup ! markdown asciidoc various wiki syntaxes (mediawiki, PmWiki) textile reStructuredText
  • 61. markdown The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. ! A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. ! The single biggest source of inspiration for Markdown’s syntax is the format of plain text e-mail. — John Gruber, Creator of Markdown
  • 62. simple (istic) can’t cover all requirements fragmentation markdown
  • 63. markdown asciidoc leanpub o’reilly github github blog platforms++ blog platforms
  • 66. proxy for docbook ! (but it’s humane)
  • 67. Output ! HTML (HTML 4, XHTML 1.1, HTML 5) DocBook PDF (fop, dblatex, custom) ePub man ODF slides deck.js, dzslides …and more !
  • 69. =  AsciiDoc  Example   Pete  Goodliffe  <pete@goodliffe.net>   ! An  optional  preface.   ! NOTE:  This  is  a  specially  formatted  note.   ! ==  First  Section   ! *  item  1   *  item  2   ! [source,ruby]   puts  "Hello,  World!"   asciidoc example
  • 70. <?xml  version="1.0"  encoding="UTF-­‐8"?>   <!DOCTYPE  book  PUBLIC  "-­‐//OASIS//DTD  DocBook  XML  V4.5//EN"          "http://www.oasis-­‐open.org/docbook/xml/4.5/docbookx.dtd">   <book  lang="en">          <bookinfo>                  <title>Asciidoc  example</title>                  <date>2014-­‐04-­‐12</date>                  <author>                          <firstname>Pete</firstname>                          <surname>Goodliffe</surname>                          <email>pete@goodliffe.net</email>                  </author>                  <authorinitials>PG</authorinitials>                  <revhistory>                          <revision>                                  <revnumber>1.0</revnumber>                                  <date>2014-­‐04-­‐12</date>                                  <authorinitials>PG</authorinitials>                          </revision>                  </revhistory>          </bookinfo> docbook equivalent
  • 71. !        <preface>                  <simpara>                          An  optional  preface.                  </simpara>                  <note>                          <simpara>                                  This  is  a  specially                                  formatted  note.                          </simpara>                  </note>          </preface>   docbook equivalent
  • 72. !        <chapter  id="_first_section">                  <title>First  section</title>                  <simpara>                          Document  sections  start  at  level  1  and                          can  nest  up  to  four  levels  deep.                  </simpara>                  <itemizedlist>                          <listitem>                                  <simpara>Item  1</simpara>                          </listitem>                          <listitem>                                  <simpara>Item  2</simpara>                          </listitem>                  </itemizedlist>   docbook equivalent
  • 73. ! ! ! ! ! !        <programlisting>                  <emphasis  role=“bold">puts</emphasis>  "Hello,  World!"          </programlisting>      </chapter>   </book>   ! ! ! ! ! ! docbook equivalent
  • 74. #  Asciidoc  example   ! An  optional  preface.   ! >  **Note**   >   >  This  is  a  specially  formatted  note.   ! ##  First  section   ! Document  sections  start  at  level  1  and  can  nest  up  to  four   levels  deep.   ! *  Item  1   *  Item  2   ! ~~~~~~~~   puts  "Hello,  World!”   ~~~~~~~~ markdown equivalent
  • 76. paragraphs Paragraphs  don't  require  any  special  markup   in  AsciiDoc.  A  paragraph  is  just  one  or  more   lines  of  consecutive  text.   ! To  begin  a  new  paragraph,  separate  it  by  at   least  one  blank  line. Paragraphs don't require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text. ! To begin a new paragraph, separate it by at least one blank line.
  • 77. headings underline Title  (Level  0)   ===============   ! Level  1   -­‐-­‐-­‐-­‐-­‐-­‐-­‐   ! Level  2   ~~~~~~~   ! Level  3   ^^^^^^^   ! Level  4   +++++++  
  • 78. headings symmetric =  Title  (Level  0)  =   ! ==  Level  1  ==   ! ===  Level  2  ===   ! ====  Level  3  ====   ! =====  Level  4  =====
  • 79. headings prefix =  Title  (Level  0)   ! ==  Level  1   ! ===  Level  2   ! ====  Level  3   ! =====  Level  4
  • 80. text “styling” This  paragraph  contains  'emphasised',   *strong*,  `monospaced`  text.   You  can  style  le**tt**ers  in  words. This paragraph contains emphasised, strong, monospaced  text. You can style letters in words.
  • 81. text “styling” This  is  text  is  _italic_.   ! This  is  inline  +source  code+. This text is italic. ! This is inline source  code.
  • 82. text “styling” That  can  apply  wi++th++in  words,  too.   Helpfully.   ! Don’t  talk  about  C++  too  much  or  C++   will  get  annoying. That can apply within words, too. Helpfully. ! Don’t talk about C  too  much  or  C will get annoying.
  • 84. text “styling” Super  script  and  subscript  are  easy.   x*x  can  be  written  as  x^2  and  you   swim  in  H~2~O. Super script and subscript are easy. x*x can be written as x2 and you swim in H2O.
  • 85. text “styling” We  break  at  the  end  of  this  line  +   to  keep  the  text  from  overflowing.  +   (It’s  a  space  then  +) We break at the end of this line to keep the text from overflowing. (It’s a space then +)
  • 86. “smart” quotes `single  smart  quotes'   ! ``double  smart  quotes'' ‘single smart quotes’ ! “double smart quotes"
  • 87. smart text replacements (C)  (R)  (TM)  -­‐-­‐  ...  -­‐>  =>     apostrophes  (auto-­‐smart)   and  more © ® ™ — … →
  • 88. literal paragraphs A  normal  paragraph.   !  A  literal  paragraph,  begins  with  at  least    one  space.  It  is  rendered  in  a  monospace    font  and  line  breaks  are  preserved.   ! Another  normal  paragraph. A normal paragraph. ! A  literal  paragraph,  begins  with  at  least   one  space.  It  is  rendered  in  a  monospace   font  and  line  breaks  are  preserved.   ! Another normal paragraph.
  • 89. footnotes Footnotes  are  simple  to  add.footnote: [They  can  be  named,  and  have  multiple   references.] Footnotes are simple to add.1 ! — 1. They can be named, and have multiple references.
  • 90. captions .Caption   Any  element  can  be  preceded  by  a   caption:  paragraphs,  blocks,  images,   and  the  like. Caption Any element can be preceded by a caption: paragraphs, blocks, images, and the like.
  • 91. literal blocks ....   Renders  as  pre-­‐formatted,  monospaced   text   .... ! Renders  as  pre-­‐formatted,  monospaced   text
  • 92. code blocks basic .Optional  caption   -­‐-­‐-­‐-­‐   public  interface  Document  {}   -­‐-­‐-­‐-­‐ ! Listing 1: Optional caption public interface Document {}!
  • 93. code blocks syntax colouring [source,c#]   .C#  (syntax  coloured)   -­‐-­‐-­‐-­‐   public  interface  Document  {}   -­‐-­‐-­‐-­‐ ! Listing 1: C# (syntax coloured) public interface Document {}!
  • 94. code blocks with callouts -­‐-­‐-­‐-­‐   public  interface  Document  <1>   {      ...                                        <2>   }   -­‐-­‐-­‐-­‐   <1>  Interface  name   <2>  Gubbins  goes  here
  • 95. source highlighting in the box, if you use in-built backends ! coderay, highlightjs, prettify, pygments :source-­‐highlighter:  pygments
  • 96. sidebar blocks .Optional  caption   ****   This  is  a  sidebar.   **** Optional caption This is a sidebar.
  • 97. quote blocks epigraphs [quote,  Albert  Einstein]   ____   Two  things  are  infinite:  the  universe  and   human  stupidity;  and  I'm  not  sure  about  the   the  universe.   ____ Two things are infinite: the universe and human stupidity; and I'm not sure about the the universe. — Albert Einstein
  • 98. quote blocks single-line [quote,  Persian  Proverb]   Thinking  well  is  wise;  planning  well,   wiser;  doing  well,  wisest  and  best   of  all. Thinking well is wise; planning well, wiser; doing well, wisest and best of all. — Persian Proverb
  • 99. passthrough blocks ++++   <p>   Content  in  a  passthrough  block  is   passed  to  the  output  unprocessed.   That  means  you  can  include  raw  HTML,   XML,  marine  life,  celestial  bodies,   etc.   </p>   ++++
  • 100. unordered lists #1 *  apple   *  orange   **  tangerine   **  satsuma   *  lemon   *  lime • apple • orange • tangerine • satsuma • lemon • lime
  • 101. unordered lists #2 *  apple   *  orange      *  tangerine      *  satsuma   *  lemon   *  lime • apple • orange • tangerine • satsuma • lemon • lime
  • 102. ordered lists 1.  one   2.  two    A.  two  a    B.  two  b   3.  three 1. one 2. two A. two a B. two b 3. three
  • 103. ordered lists implicit numbering .  one   .  two   ..  two  a   ..  two  b   .  three 1. one 2. two A. two a B. two b 3. three
  • 104. definition lists single-line first  term::  definition  of  first  term   section  term::  definition  of  second   term first term definition of first term ! section term definition of second term
  • 105. definition lists multi-line first  term::   definition  of  first  term   section  term::   definition  of  second  term first term definition of first term ! section term definition of second term
  • 106. links http://asciidoc.org.   ! Read  about  the  http://asciidoc.org[AsciiDoc  Project].   Note  the  full-­‐stop  handles  correctly.  Hurrah!   ! http://asciidoc.org. ! Read about the AsciiDoc Project. Note the full-stop handles correctly. Hurrah!
  • 107. cross references [[anchor]]Internal  link  anchor  here.   ! Go  to  <<anchor,internal  link>>.   Internal link anchor here. ! Go to internal link.
  • 108. links ! pete@goodliffe.net   ! Mail  mailto:pete@goodliffe.net[Pete  Goodliffe]   ! irc://chat.freenode.net/#accu   ! pete@goodliffe.net ! Mail Pete Goodliffe ! irc://chat.freenode.net/#accu
  • 109. images Inline   image:images/image.png[Alt  text]   ! Block   image::images/image.png[Alt  text]   ! .Block  with  caption   image::images/image.png[Alt  text]
  • 110. admonitions NOTE:  A  single  line  note.   ! [NOTE]   Or  this  as  an  alternative.   ! [NOTE]   ====   Or  this  as  an  alternative   that  can  span  multiple  blocks,  and  even  include   * lists   * and  other  things   ==== NOTE: A single line note ! NOTE: Or this as an alternative.
  • 112. comments This  is  in  the  document.   //  This  line  has  been  removed   ! You  can  throw  a  processor  switch  to   conditionally  include  comments. This is in the document. ! You can throw a processor switch to conditionally include comments.
  • 113. comment blocks You  can  also  have  multi-­‐line  comments…  in  a  block!   ! ////   A  multi-­‐line  comment.   ! Notice  it's  a  delimited  block.   //// You can also have multi-line comments… in a block!
  • 114. tables .Table  Title   |===   |Name  of  Col  1  |Name  of  Col  2  |Name  of  Col  3     ! |Cell  in  column  1,  row  1   |Cell  in  column  2,  row  1   |Cell  in  column  3,  row  1   ! |Cell  in  column  1,  row  2   |Cell  in  column  2,  row  2   |Cell  in  column  3,  row  2   |===  
  • 115. tables ! ! .Table  Title   |===   |Name  of  Col  1  |Name  of  Col  2  |Name  of  Col  3     ! |column  1,  row  1  |  col  2  |  col  3   |column  2,  row  2  |  col  2  |  col  3   |column  3,  row  3  |  col  2  |  col  3   |===   ! !
  • 116. attributes and substitutions :homepage:  http://www.goodliffe.net   ! Check  out  {homepage}[my  homepage].   Check out my homepage.
  • 117. attributes and conditionals :experimental:  yes   ! Normal  text   ! ifdef::experimental[]   This  text  is  only  included  if  experimental  is  defined.   endif::experimental[] Normal text ! This text is only included if experimental is defined. or… asciidoc -a experimental=yes …
  • 118. table of contents :toc:   //  that  “enables”  TOC  generation;   //  it  will  be  inserted  in  the  right   //  place  magically Table of Contents Chapter 1 … … … … … … … … Page 1 Chapter 2 … … … … … … … … Page 10 Chapter 3 … … … … … … … … Page 23
  • 119. bibliography ‘Code  Craft'  <<codecraft>>  is  a  marvellous  book.   ! [bibliography]   -­‐  [[[codecraft]]]  Pete  Goodliffe.  ‘Code  Craft:      The  Practice  of  Writing  Excellent  Code'.        No  Starch  Press.  2005. Code Craft [codecraft] is a marvellous book. ! Bibliography [codecraft] Pete Goodliffe. ‘Code Craft: The Practive of Writing Excellent Code’. No Start Press. 2005.
  • 122. includes allow for a sane file structure, and a beautiful top-level file
  • 123. Becoming  a  Better  Programmer   ============================   :author:        Pete  Goodliffe   :email:          pete@goodliffe.net   :date:            2014-­‐04-­‐01   :revision:    0.00   :doctype:      book   :lang:            en   ! :toc:   :toc-­‐placement:  manual   :toc-­‐title:   :toclevels:  1   :numbered!:   ! ////////////////////////////////////////////////////////////////////////////////   This  is  an  example  of  the  source  for  my  new  book.   This  is  the  book.asciidoc  file.  It  has  no  content  itself,  just  preamble   and  includes  for  other  files.   ////////////////////////////////////////////////////////////////////////////////   ! //  Frontmatter   include::frontmatter/legal.asciidoc[]   include::frontmatter/dedication.asciidoc[]   include::frontmatter/author.asciidoc[]   include::frontmatter/intro.asciidoc[]   ! //  Chapters   include::chapters/CareAboutTheCode.asciidoc[]   include::chapters/PeoplePower.asciidoc[]   ! //  ...  and  so  on  ...
  • 125. custom styling (“roles”) for when you really, absolutely, have to (i.e. not often) The  following  [custom_role]#word#  is   given  a  custom  role. The following <span class=“custom_role”>word</ span> is given a custom role.
  • 126. block metadata .Gettysburg  Address   [[gettysburg]]   [quote,  Abraham  Lincoln,  Soldiers'  National   Cemetery  Dedication]   ____   Four  score  and  seven  years  ago  our  fathers   brought  forth   on  this  continent  a  new  nation...   ! Now  we  are  engaged  in  a  great  civil  war,  testing   whether   that  nation,  or  any  nation  so  conceived  and  so   dedicated,   can  long  endure.  ...   ____ title id style (role) named attributes
  • 128. asciidoc.py <- the tool -b <xhtml11, epub, pdf> <- backend -o output.html <- output source.asciidoc <- input
  • 130. don’t over-style for visual appearance (visuals are determined by backend) ! use structure to emphasise and highlight your text
  • 131. don’t try to force your text into a different structure ! use headings, subheadings, unordered lists, lists, admonitions, definition lists ! captions are not subheads bold is not a subhead definition lists are for lists, not for subheads
  • 133. index terms indexterm:[Tigers,Big  cats]   (((Tigers,Big  cats))) Index Tigers, A silly index entry, 134 Big cats, 10 In literature, 12
  • 134. index terms This  is  a  book  all  about  ((tigers)).   ! indexterm2:[tigers] This is a book all about tigers. ! Index Tigers, 10
  • 135. for docbook (and epub) ! the index toolchain just works
  • 137. $(FLEXNDEX_VERSION): $(ASCIIDOC) cp -r src $(FLEXNDEX_VERSION) find $(FLEXNDEX_VERSION) -name "*.asciidoc" | xargs sed -i flextmp -e 's/(((/=[/g' -e 's/)))/]=/g' the pre-process munge
  • 138. asciidoc.conf # "Standard" flexndex kinda macros, to set up # ix:myindex[term] (where "term" is an entry in the index "myindex") # ixhere::myindex[] (the index "myindex" is generated here) (?su)(?P<name>ix):(?P<target>S*?)([(?P<attrlist>.*?)])= (?u)^(?P<name>ixhere)::(?P<target>S*?)([(?P<attrlist>.*?)])$=# ! [ix-inlinemacro] <!-- ix {target} <{attrlist}> --> ! [ixhere-blockmacro] <!-- ixhere {target} <{attrlist=}> —> ! # Pete's preferred cunning: # =[term]= defines an index term here, in the hardcoded index # "myindex" # (still use ixhere:myindex[] to generate that index) =[(?P<attrlist>.*?)]==ixsingle ! [ixsingle-inlinemacro] <!-- ix myindex <{attrlist}> -->
  • 140. flexndex.conf ! (mostly just stuff) default_style=simple-grouped ! [styles.simple-grouped.xhtml11] ! prefix=<div class="flexndex-index"> postfix=</div> ! levels.1.text_internal = levels.1.link_last = <p><!--(1.link_last)-->{ixterm},{sp}<a href="#ix{ixtgt}" class="notext">{ixterm}</a> levels.1.text_last = <p><!--(1.text_last)-->{ixterm} levels.1.multi_target = <!--(1.multi_target)-->,{sp}<a href="#ix{ixtgt}" class="notext">{ixtext}</a> ! levels.2.text_internal = levels.2.link_last = <p style="text-indent:{ixindent}em;">&nbsp;&nbsp;&nbsp;<!--(levels.2.link_last)-- >{ixterm},{sp}<a href="#ix{ixtgt}" class="notext">{ixterm}</a> levels.2.text_last = <p style="text-indent:{ixindent}em;">&nbsp;&nbsp;&nbsp;<!--(levels.2.text_last)-- >{ixterm} levels.2.multi_target = <!--(levels.2.multi_target)-->,{sp}<a href="#ix{ixtgt}" class="notext">{ixtext}</a> ! entry_start=<!--(entry_start)--> entry_end=<!--(entry_end)--></p>{nl} complete=e
  • 141. <div class="sect1"> <h2 id="_index">Index</h2> <div class="sectionbody"> <div class=“flexndex-index"> <!—(entry_start)--> <p> <!--(1.text_last)-->API<!--(1.multi_target)-->, <a href="#ix158" class=“notext">API</a><!--(1.multi_target)-->, <a href="#ix144" class=“notext">API</a><!--(entry_end)--> </p> html output
  • 143. asciidoc.py -b pdf -d book -a <some attributes> -o $(HTML_OUT) $(BOOK_SOURCE)
  • 146. all you have to do now is learn CSS
  • 148. final pdf steps ! pdftk “If PDF is electronic paper, then pdftk is an electronic staple-remover, hole-punch, binder, secret-decoder-ring, and X-Ray-glasses.”
  • 149. pdftk ! update pdf metadata (creator, title, author, keywords) cut pages out merge pages (e.g. add cover) adjust page bookmarks
  • 153. ************************************************************* Amazon kindlegen(MAC OSX) V2.8 build 0208-797bf75 A command line e-book compiler Copyright Amazon.com and its Affiliates 2013 ************************************************************* !Info:I9007:option: -c2: Kindle Huffdic compression Info(prcgen):I1047: Added metadata dc:Title "Becoming a Better Programmer" Info(prcgen):I1047: Added metadata dc:Date "2014-03-26" Info(prcgen):I1047: Added metadata dc:Creator "Pete Goodliffe" Info(prcgen):I1052: Kindle support cover images but does not support cover HTML. Hence using the cover image specified and suppressing cover HTML in content. URL: /var/folders/0t/ 2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/cover.html Info(prcgen):I1002: Parsing files 0000025 Info(cssparser):I10004: @rules other than @import, @charset and @font-face are not supported. Warning(htmlprocessor):W28001: CSS style specified in content is not supported by Kindle readers. Removing the CSS property: 'max-width' in file: /var/folders/0t/ 2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/css/epub.css Warning(htmlprocessor):W28001: CSS style specified in content is not supported by Kindle readers. Removing the CSS property: 'max-height' in file: /var/folders/0t/ 2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/css/epub.css Warning(inputpreprocessor):W29004: Forcefully closed opened Tag: <dl> in file: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/ix01.html line: 0000002 Warning(inputpreprocessor):W29004: Forcefully closed opened Tag: <dd> in file: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/ix01.html line: 0000002 Warning(inputpreprocessor):W29010: Tag rejected due to being used in unauthorized scope: <dt> in file: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/ix01.html line: 0000002 Warning(inputpreprocessor):W29010: Tag rejected due to being used in unauthorized scope: <dd> in file: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/ix01.html line: 0000002 Info(prcgen):I1016: Building enhanced PRC file Info(prcgen):I1015: Building PRC file Info(prcgen):I1006: Resolving hyperlinks Info(prcgen):I1049: Building table of content URL: /var/folders/0t/2f63pw6d03l8cp6rj9m7bcv00000gn/T/mobi-Zz0bcy/OEBPS/toc.ncx Info(pagemap):I8000: No Page map found in the book Info(prcgen):I1045: Computing UNICODE ranges used in the book Info(prcgen):I1046: Found UNICODE range: Basic Latin [20..7E] Info(prcgen):I1046: Found UNICODE range: Latin-1 Supplement [A0..FF] Info(prcgen):I1046: Found UNICODE range: General Punctuation - Windows 1252 [2018..201A] Info(prcgen):I1046: Found UNICODE range: Letter-like Symbols [2100..214F] Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000001 Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000002 Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000004 Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000008 Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000016 Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000032 Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000064 Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000128 Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000256 Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Pass 0000442 Info(prcgen/compress):I4002: Compression pass 0000001 Info(prcgen/compress):I4002: Compression pass 0000002 Info(prcgen/compress):I4002: Compression pass 0000003 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 41.63% Info(prcgen/compress):I4007: Compression dictionary statistics: 000062574 bytes 000005159 entries Info(prcgen/compress):I4002: Compression pass 0000004 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 36.19% Info(prcgen/compress):I4007: Compression dictionary statistics: 000042590 bytes 000003796 entries Info(prcgen/compress):I4002: Compression pass 0000005 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 34.86% Info(prcgen/compress):I4007: Compression dictionary statistics: 000036228 bytes 000003033 entries Info(prcgen/compress):I4002: Compression pass 0000006 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 33.98% Info(prcgen/compress):I4007: Compression dictionary statistics: 000030660 bytes 000002441 entries Info(prcgen/compress):I4002: Compression pass 0000007 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 32.41% Info(prcgen/compress):I4007: Compression dictionary statistics: 000022576 bytes 000001967 entries Info(prcgen/compress):I4002: Compression pass 0000008 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 32.37% Info(prcgen/compress):I4007: Compression dictionary statistics: 000019490 bytes 000001595 entries Info(prcgen/compress):I4002: Compression pass 0000009 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 32.54% Info(prcgen/compress):I4007: Compression dictionary statistics: 000017004 bytes 000001296 entries ! Info(prcgen/compress):I4005: Advanced compression successful (decoded and verified). Info(prcgen):I1039: Final stats - text compressed to (in % of original size): 32.54% Info(prcgen):I1040: The document identifier is: "Becoming_a_B-ter_Programmer" Info(prcgen):I1041: The file format version is V6 Info(prcgen):I1031: Saving PRC file Info(prcgen):I1032: PRC built successfully Info(prcgen):I1007: Resolving mediaidlinks Info(prcgen):I1011: Writing mediaidlinks Info(prcgen):I1009: Resolving guide items Info(prcgen/compress):I4001: Compiling source text for compression (4096 passes max). Info(prcgen/compress):I4006: Text compressed to (in % of original size): 45.26% Info(prcgen/compress):I4007: Compression dictionary statistics: 000073362 bytes 0000 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 42.31% Info(prcgen/compress):I4007: Compression dictionary statistics: 000059026 bytes 0000 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 38.80% Info(prcgen/compress):I4007: Compression dictionary statistics: 000042640 bytes 0000 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 37.97% Info(prcgen/compress):I4007: Compression dictionary statistics: 000035726 bytes 0000 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 37.69% Info(prcgen/compress):I4007: Compression dictionary statistics: 000030582 bytes 0000 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 36.61% Info(prcgen/compress):I4007: Compression dictionary statistics: 000022696 bytes 0000 Info(prcgen/compress):I4006: Text compressed to (in % of original size): 36.79% Info(prcgen/compress):I4007: Compression dictionary statistics: 000019762 bytes 0000 Info(prcgen):I1039: Final stats - text compressed to (in % of original size): 36.79% Info(prcgen):I1041: The file format version is V8 Info(prcgen):I15000: Approximate Standard Mobi Deliverable file size : 0001661KB Info(prcgen):I15001: Approximate KF8 Deliverable file size : 0001702KB Info(prcgen):I1036: Mobi file built successfully Ta da!
  • 156. leanpub iBookstore, kindle direct publishing, kobo, B&N scribd ! lulu, blurb, createspace, completelynovel ! gumroad, sellfy, selz ! smashwords, bookbaby ! actual factual publisher
  • 157. isbns
  • 158. amazon $0-2.98 or $10.00+ 35% $2.99-$9.99 70% ! iBookstore 70% ! smashwords ~60% list (85% on their store) ! consider: delay to payment
  • 162. dropbox online generation ! not in manuscript title // subtitle // dedication legal info // cover // etc
  • 163. - - - markdown restricted not (very) customisable frumpy ! + + + bookstore sample versions pay what you like easy update
  • 169. - - - you’re in control poor for sample versions no “bookstore” you’re doing all the marketing ! + + + you’re in control cost analytics website integration widget thingy
  • 170. flat fee 5% + 25¢
  • 174. leanpub 118 d/l in 5w ! gumroad 28 purchases (423 views) 62 samples (259 views)
  • 176. technical edit copy edit write production first draft final draft proposal deal advance royalty tree/electrons about book the market table of contents competitors sample chapters deadline! indexing layout cover
  • 177. how rich will i get?
  • 178. Writing a book is a horrible, exhausting struggle, like a long bout with some painful illness. One would never undertake such a thing if one were not driven on by some demon whom one can neither resist nor understand. ! George Orwell
  • 183. Icons Book by Pedro Lalli from The Noun Project Document by Piotrek Chuchla from The Noun Project Magazine by Evan Travelstead from The Noun Project Translation by Lek Potharam from The Noun Project Code by Darren Barone from The Noun Project Time Out by Peacock Dream from The Noun Project Cry by Austin Condiff from The Noun Project Eye by Eugen Belyakoff from The Noun Project Poop by Mourad Mokrane from The Noun Project Folder by Hunor Csaszar from The Noun Project Bolt by Ilsur Aptukov from The Noun Project ! All other icons are in the public domain Credits
  • 184. Interesting references ! AsciiDoc Syntax Quick Reference http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ ! (Ascii)Docs with pleasure! http://mojavelinux.github.io/decks/asciidoc-with-pleasure/#31.1 Further reading