Diese Präsentation wurde erfolgreich gemeldet.
Die SlideShare-Präsentation wird heruntergeladen. ×

Words in Code

A presentation given at ACCU 2014.

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 HTML, PDF (fully styled, print-ready) ePub and Kindle output, as well as Word-friendly versions.

A presentation given at ACCU 2014.

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 HTML, PDF (fully styled, print-ready) ePub and Kindle output, as well as Word-friendly versions.

Weitere Verwandte Inhalte

Ähnliche Bücher

Kostenlos mit einer 30-tägigen Testversion von Scribd

Alle anzeigen

Ähnliche Hörbücher

Kostenlos mit einer 30-tägigen Testversion von Scribd

Alle anzeigen

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
  3. <head>
  4. #1 #2 #3 recap
  5. how / what mechanisms for writing writing style available tools — a toolchain publishing
  6. what do i know about this?
  7. << docbook latex framemaker
  8. mediawiki >>
  9. << word odt text asciidoc (framemaker)
  10. asciidoc >> html css epub limited time discount http://gum.co/ becomingbetter/accu2014
  11. word
  12. <body>
  13. on writing <section>
  14. all programmers should do it
  15. Thinking for Programmers Leslie Lamport, Build 2014
  16. what how?
  17. what? (do you know)
  18. Either write something worth reading or do something worth writing. ! Benjamin Franklin
  19. how?
  20. 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
  21. good writing style
  22. read ! (a lot)
  23. If you don't have time to read, you don't have the time (or the tools) to write. Simple as that. ! Stephen King
  24. 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)
  25. The most valuable of all talents is that of never using two words when one will do. ! Thomas Jefferson
  26. & <section>
  27. plain text TEX / LA TEX RTF HTML word/open office/pages/etc docbook lightweight markup
  28. doxygen ndoc javadoc etcdocthings
  29. plain text primitive // lingua franca // core unix // ebcdic, ascii, unicode
  30. 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  
  31. TEX
  32. LATEX
  33. 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
  34. 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
  35. RTF
  36. {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:
  37. HTML
  38. ! <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">   —  Lao  Tzu   </div></div>   <div  class="paragraph"><p><!-­‐-­‐  ix  myindex  <Caring>  -­‐-­‐><a  id="ix0"></a>   It  doesn’t  take  Sherlock  Holmes  to  work  out  that  good  programmers   write   good  code.  Bad  programmers…  don’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’t  pop  out  of  thin  air.   It  isn’t  something  that  happens   by  luck  when  the  planets  align.  To  get  good  code  you  have  to  work  at  it.   Hard.  And  you’ll  only  get  good  code  if  you  actually  <em>care</em>   about  good   code.</p></div>  
  39. docbook
  40. <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>  
  41. wysiwyg ! word/open office/pages/etc
  42. wysiwyg ! (inwyw)
  43. styles maths version control file format control collaboration including source code multiple outputs
  44. your document structure (this sucks)
  45. initial version add chapter 2 update introduction fix typo in chapter 1 add dancing leprechauns version control log
  46. diff it ! go on, i dare you
  47. one file has all of the things
  48. all text content all graphics all style information all structure all indexing
  49. (you wouldn’t do that with your source code)
  50. my_book.thing introduction.thing chapter1.thing chapter2.thing graphics graphic.png my_awesome_book my ideal world
  51. there is a better way
  52. lightweight markup ! markdown asciidoc various wiki syntaxes (mediawiki, PmWiki) textile reStructuredText
  53. lightweight markup ! markdown asciidoc various wiki syntaxes (mediawiki, PmWiki) textile reStructuredText
  54. humane
  55. 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
  56. simple (istic) can’t cover all requirements fragmentation markdown
  57. markdown asciidoc leanpub o’reilly github github blog platforms++ blog platforms
  58. markdown asciidoc limited restricted toolchain docbook equivalent richer toolchain
  59. asciidoc <section>
  60. proxy for docbook ! (but it’s humane)
  61. Output ! HTML (HTML 4, XHTML 1.1, HTML 5) DocBook PDF (fop, dblatex, custom) ePub man ODF slides deck.js, dzslides …and more !
  62. readable concise comprehensive extensible mature, high-quality produces beautiful output
  63. =  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
  64. <?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
  65. !        <preface>                  <simpara>                          An  optional  preface.                  </simpara>                  <note>                          <simpara>                                  This  is  a  specially                                  formatted  note.                          </simpara>                  </note>          </preface>   docbook equivalent
  66. !        <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
  67. ! ! ! ! ! !        <programlisting>                  <emphasis  role=“bold">puts</emphasis>  "Hello,  World!"          </programlisting>      </chapter>   </book>   ! ! ! ! ! ! docbook equivalent
  68. #  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
  69. asciidoc syntax
  70. 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.
  71. headings underline Title  (Level  0)   ===============   ! Level  1   -­‐-­‐-­‐-­‐-­‐-­‐-­‐   ! Level  2   ~~~~~~~   ! Level  3   ^^^^^^^   ! Level  4   +++++++  
  72. headings symmetric =  Title  (Level  0)  =   ! ==  Level  1  ==   ! ===  Level  2  ===   ! ====  Level  3  ====   ! =====  Level  4  =====
  73. headings prefix =  Title  (Level  0)   ! ==  Level  1   ! ===  Level  2   ! ====  Level  3   ! =====  Level  4
  74. 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.
  75. text “styling” This  is  text  is  _italic_.   ! This  is  inline  +source  code+. This text is italic. ! This is inline source  code.
  76. 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.
  77. shucks C+{empty}+ C++
  78. 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.
  79. 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 +)
  80. “smart” quotes `single  smart  quotes'   ! ``double  smart  quotes'' ‘single smart quotes’ ! “double smart quotes"
  81. smart text replacements (C)  (R)  (TM)  -­‐-­‐  ...  -­‐>  =>     apostrophes  (auto-­‐smart)   and  more © ® ™ — … →
  82. 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.
  83. 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.
  84. 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.
  85. literal blocks ....   Renders  as  pre-­‐formatted,  monospaced   text   .... ! Renders  as  pre-­‐formatted,  monospaced   text
  86. code blocks basic .Optional  caption   -­‐-­‐-­‐-­‐   public  interface  Document  {}   -­‐-­‐-­‐-­‐ ! Listing 1: Optional caption public interface Document {}!
  87. code blocks syntax colouring [source,c#]   .C#  (syntax  coloured)   -­‐-­‐-­‐-­‐   public  interface  Document  {}   -­‐-­‐-­‐-­‐ ! Listing 1: C# (syntax coloured) public interface Document {}!
  88. code blocks with callouts -­‐-­‐-­‐-­‐   public  interface  Document  <1>   {      ...                                        <2>   }   -­‐-­‐-­‐-­‐   <1>  Interface  name   <2>  Gubbins  goes  here
  89. source highlighting in the box, if you use in-built backends ! coderay, highlightjs, prettify, pygments :source-­‐highlighter:  pygments
  90. sidebar blocks .Optional  caption   ****   This  is  a  sidebar.   **** Optional caption This is a sidebar.
  91. 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
  92. 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
  93. 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>   ++++
  94. unordered lists #1 *  apple   *  orange   **  tangerine   **  satsuma   *  lemon   *  lime • apple • orange • tangerine • satsuma • lemon • lime
  95. unordered lists #2 *  apple   *  orange      *  tangerine      *  satsuma   *  lemon   *  lime • apple • orange • tangerine • satsuma • lemon • lime
  96. 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
  97. ordered lists implicit numbering .  one   .  two   ..  two  a   ..  two  b   .  three 1. one 2. two A. two a B. two b 3. three
  98. 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
  99. 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
  100. 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!
  101. cross references [[anchor]]Internal  link  anchor  here.   ! Go  to  <<anchor,internal  link>>.   Internal link anchor here. ! Go to internal link.
  102. 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
  103. images Inline   image:images/image.png[Alt  text]   ! Block   image::images/image.png[Alt  text]   ! .Block  with  caption   image::images/image.png[Alt  text]
  104. 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.
  105. admonitions TIP: NOTE: IMPORTANT: WARNING: CAUTION:
  106. 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.
  107. 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!
  108. 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   |===  
  109. 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   |===   ! !
  110. attributes and substitutions :homepage:  http://www.goodliffe.net   ! Check  out  {homepage}[my  homepage].   Check out my homepage.
  111. 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 …
  112. 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
  113. 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.
  114. includes include::chapter.asciidoc[]
  115. includes ! ! ! ! ! :a-­‐base—source:  https://www.goodliffe.net/ example   ! include::{a-­‐base—source}/file.asciidoc[]   ! ! ! !
  116. includes allow for a sane file structure, and a beautiful top-level file
  117. 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  ...
  118. book.asciidoc introduction.asciidoc chapter1.asciidoc chapter2.asciidoc graphics graphic.png my_awesome_book achievement unlocked
  119. 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.
  120. 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
  121. asciidoc toolchains ! asciidoc (python) asciidoctor (ruby) pandoc (haskell)
  122. asciidoc.py <- the tool -b <xhtml11, epub, pdf> <- backend -o output.html <- output source.asciidoc <- input
  123. practical asciidoc
  124. don’t over-style for visual appearance (visuals are determined by backend) ! use structure to emphasise and highlight your text
  125. 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
  126. indexing
  127. index terms indexterm:[Tigers,Big  cats]   (((Tigers,Big  cats))) Index Tigers, A silly index entry, 134 Big cats, 10 In literature, 12
  128. index terms This  is  a  book  all  about  ((tigers)).   ! indexterm2:[tigers] This is a book all about tigers. ! Index Tigers, 10
  129. for docbook (and epub) ! the index toolchain just works
  130. flexndex ! https://github.com/elextr/flexndex
  131. $(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
  132. 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}> -->
  133. flexndex.py $(HTML_OUT) $(HTML_OUT).flexndex --config $(FLEXNDEX_CONF) flexndexery
  134. 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
  135. <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
  136. pdf tooling
  137. asciidoc.py -b pdf -d book -a <some attributes> -o $(HTML_OUT) $(BOOK_SOURCE)
  138. asciidoc html pdf css
  139. asciidoc html pdf pdf css epub epub css
  140. all you have to do now is learn CSS
  141. PrinceXML http://www.princexml.com ! WeasyPrint http://weasyprint.org ! xhtml2pdf http://www.xhtml2pdf.com ! wkhtmltopdf http://wkhtmltopdf.org
  142. 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.”
  143. pdftk ! update pdf metadata (creator, title, author, keywords) cut pages out merge pages (e.g. add cover) adjust page bookmarks
  144. mobi tooling for the kindle
  145. epub mobi kindlegen
  146. kindlegen book.epub -c2 -verbose -o book.mobi
  147. ************************************************************* 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!
  148. demonstration
  149. selling your book <section>
  150. leanpub iBookstore, kindle direct publishing, kobo, B&N scribd ! lulu, blurb, createspace, completelynovel ! gumroad, sellfy, selz ! smashwords, bookbaby ! actual factual publisher
  151. isbns
  152. 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
  153. dropbox online generation ! not in manuscript title // subtitle // dedication legal info // cover // etc
  154. - - - markdown restricted not (very) customisable frumpy ! + + + bookstore sample versions pay what you like easy update
  155. flat fee 10% + 50¢
  156. - - - 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
  157. flat fee 5% + 25¢
  158. launch strategy
  159. drive sales
  160. sales figures…
  161. leanpub 118 d/l in 5w ! gumroad 28 purchases (423 views) 62 samples (259 views)
  162. “proper” publisher
  163. 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
  164. how rich will i get?
  165. 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
  166. </body>
  167. TL;DR (write!)
  168. limited time discount http://gum.co/becomingbetter/accu2014 @petegoodliffe
  169. Thank you for listening
  170. 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
  171. 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

×