From mike at pythonlibrary.org Sat Apr 20 19:14:17 2013 From: mike at pythonlibrary.org (Mike Driscoll) Date: Sat, 20 Apr 2013 12:14:17 -0500 Subject: [Python-authors] Book writing software Message-ID: Hi, I keep thinking I need to write a Python book and I think I'm finally ready to start. Can anyone tell me what software they recommend for writing the book in? I hate MS Word for writing long documents with markup, but I don't think Notepad++ really makes sense either. Any ideas would be appreciated. Thanks! ------------------- Mike Driscoll Blog: http://blog.pythonlibrary.org -------------- next part -------------- An HTML attachment was scrubbed... URL: From aahz at pythoncraft.com Sat Apr 20 19:21:26 2013 From: aahz at pythoncraft.com (Aahz) Date: Sat, 20 Apr 2013 10:21:26 -0700 Subject: [Python-authors] Book writing software In-Reply-To: References: Message-ID: <20130420172125.GB5409@panix.com> On Sat, Apr 20, 2013, Mike Driscoll wrote: > > I keep thinking I need to write a Python book and I think I'm finally ready > to start. Can anyone tell me what software they recommend for writing the > book in? I hate MS Word for writing long documents with markup, but I don't > think Notepad++ really makes sense either. > > Any ideas would be appreciated. Thanks! vim and reStructuredText, will likely need some coding work to get into an output format if you got through a publishing house. -- Aahz (aahz at pythoncraft.com) <*> http://www.pythoncraft.com/ "In theory, there is no difference between theory and practice. But, in practice, there is." --Jan L.A. van de Snepscheut From naomi.ceder at gmail.com Sat Apr 20 19:24:49 2013 From: naomi.ceder at gmail.com (Naomi Ceder) Date: Sat, 20 Apr 2013 12:24:49 -0500 Subject: [Python-authors] Book writing software In-Reply-To: References: Message-ID: On Sat, Apr 20, 2013 at 12:14 PM, Mike Driscoll wrote: > Hi, > > I keep thinking I need to write a Python book and I think I'm finally > ready to start. Can anyone tell me what software they recommend for writing > the book in? I hate MS Word for writing long documents with markup, but I > don't think Notepad++ really makes sense either. > > Any ideas would be appreciated. Thanks! > For me the choice was largely determined by the publisher's requirements, so I have suffered through using Word (and Open Office, since it crashed less frequently). No useful advice from me, just a caveat. The real pain point I've always felt is keeping code snippets current through testing and revision. I know that some people have been working on solutions to this issue. I can tell you that managing code when writing in something like Word is a total nightmare. > ------------------- > Mike Driscoll > > Blog: http://blog.pythonlibrary.org > > _______________________________________________ > Python-authors mailing list > Python-authors at python.org > http://mail.python.org/mailman/listinfo/python-authors > > -- Naomi Ceder https://plus.google.com/u/0/111396744045017339164/about -------------- next part -------------- An HTML attachment was scrubbed... URL: From vasudevram at gmail.com Sat Apr 20 19:33:41 2013 From: vasudevram at gmail.com (Vasudev Ram) Date: Sat, 20 Apr 2013 23:03:41 +0530 Subject: [Python-authors] Book writing software In-Reply-To: References:

Message-ID: IMO, what software you use depends at least to some extent on whether you're planning to self-publish it or use some kind of publisher, either one of the traditional ones or the online ones. If you use a publisher they'll likely have some restrictions about the kinds of software you can use to write the book with. If you're publishing yourself, the field is wide open, as to the choice of software you use, as long as whatever you use meets your needs not only during the writing process, but also during the process of creating the final product in different formats - print or ebooks - and in ebooks, what formats: PDF, .mobi, EPUB, HTML, etc. Some options to check out (you may know them already): - Lulu.com - Leanpub.com - Amazon CreateSpace And there are others. HTH Vasudev Inspired by nature. - dancingbison.com | @vasudevram | jugad2.blogspot.com On Sat, Apr 20, 2013 at 10:54 PM, Naomi Ceder wrote: > On Sat, Apr 20, 2013 at 12:14 PM, Mike Driscoll wrote: > >> Hi, >> >> I keep thinking I need to write a Python book and I think I'm finally >> ready to start. Can anyone tell me what software they recommend for writing >> the book in? I hate MS Word for writing long documents with markup, but I >> don't think Notepad++ really makes sense either. >> >> Any ideas would be appreciated. Thanks! >> > > For me the choice was largely determined by the publisher's requirements, > so I have suffered through using Word (and Open Office, since it crashed > less frequently). > > No useful advice from me, just a caveat. The real pain point I've always > felt is keeping code snippets current through testing and revision. I know > that some people have been working on solutions to this issue. I can tell > you that managing code when writing in something like Word is a total > nightmare. > > > >> ------------------- >> Mike Driscoll >> >> Blog: http://blog.pythonlibrary.org >> >> _______________________________________________ >> Python-authors mailing list >> Python-authors at python.org >> http://mail.python.org/mailman/listinfo/python-authors >> >> > > > -- > Naomi Ceder > https://plus.google.com/u/0/111396744045017339164/about > > _______________________________________________ > Python-authors mailing list > Python-authors at python.org > http://mail.python.org/mailman/listinfo/python-authors > > -------------- next part -------------- An HTML attachment was scrubbed... URL: From mike at pythonlibrary.org Sat Apr 20 20:09:39 2013 From: mike at pythonlibrary.org (Mike Driscoll) Date: Sat, 20 Apr 2013 13:09:39 -0500 Subject: [Python-authors] Book writing software In-Reply-To: References:

Message-ID: Hi everyone, I'm going to go the self-publishing route. Right now, I'm going to focus on ebooks, although converting it to print would be fun later on. - Mike On Sat, Apr 20, 2013 at 12:33 PM, Vasudev Ram wrote: > > IMO, what software you use depends at least to some extent on whether > you're planning to self-publish it or use some kind of publisher, either > one of the traditional ones or the online ones. If you use a publisher > they'll likely have some restrictions about the kinds of software you can > use to write the book with. If you're publishing yourself, the field is > wide open, as to the choice of software you use, as long as whatever you > use meets your needs not only during the writing process, but also during > the process of creating the final product in different formats - print or > ebooks - and in ebooks, what formats: PDF, .mobi, EPUB, HTML, etc. > > Some options to check out (you may know them already): > > - Lulu.com > > - Leanpub.com > > - Amazon CreateSpace > > And there are others. > > HTH > Vasudev > > Inspired by nature. > - dancingbison.com | @vasudevram | jugad2.blogspot.com > > > On Sat, Apr 20, 2013 at 10:54 PM, Naomi Ceder wrote: > >> On Sat, Apr 20, 2013 at 12:14 PM, Mike Driscoll wrote: >> >>> Hi, >>> >>> I keep thinking I need to write a Python book and I think I'm finally >>> ready to start. Can anyone tell me what software they recommend for writing >>> the book in? I hate MS Word for writing long documents with markup, but I >>> don't think Notepad++ really makes sense either. >>> >>> Any ideas would be appreciated. Thanks! >>> >> >> For me the choice was largely determined by the publisher's requirements, >> so I have suffered through using Word (and Open Office, since it crashed >> less frequently). >> >> No useful advice from me, just a caveat. The real pain point I've always >> felt is keeping code snippets current through testing and revision. I know >> that some people have been working on solutions to this issue. I can tell >> you that managing code when writing in something like Word is a total >> nightmare. >> >> >> >>> ------------------- >>> Mike Driscoll >>> >>> Blog: http://blog.pythonlibrary.org >>> >>> _______________________________________________ >>> Python-authors mailing list >>> Python-authors at python.org >>> http://mail.python.org/mailman/listinfo/python-authors >>> >>> >> >> >> -- >> Naomi Ceder >> https://plus.google.com/u/0/111396744045017339164/about >> >> _______________________________________________ >> Python-authors mailing list >> Python-authors at python.org >> http://mail.python.org/mailman/listinfo/python-authors >> >> > -- ----------------- Mike Driscoll Blog: http://blog.pythonlibrary.org -------------- next part -------------- An HTML attachment was scrubbed... URL: From vasudevram at gmail.com Sat Apr 20 20:25:35 2013 From: vasudevram at gmail.com (Vasudev Ram) Date: Sat, 20 Apr 2013 23:55:35 +0530 Subject: [Python-authors] Book writing software In-Reply-To: References:

Message-ID: Forgot to mention that you can use my xtopdf toolkit to very easily create at least early drafts of a PDF ebook, though only if the book consists of text only - images and other features are not supported. There are two ways you can use it: If you can arrange for your book draft (at least in the early stages of writing) to consist of a set of text files, one per chapter, then the PDF can be created simply running PDFBook.py, which is included with the xtopdf package. Using PDFBook.py in this way may be useful to create early drafts as PDF, and send them to others for review, to review yourself, or to take printouts of, for review. Run PDFBook.py without arguments to see the usage. If you want more programmatic control, another possibility is to read your book text into a Python program and then use the PDFWriter class in the PDFWriter.py module, to generate the output. This will let you set different fonts for different parts of the book, same for headers / footers, and control where pages break. Take a look at PDFWriter.py - the main() function includes examples of how to use the class. The latest version of xtopdf is at https://bitbucket.org/vasudevram/xtopdf Tabular output - from CSV / TSV / XLS data - can also be created in the PDF using xtopdf; see this article for some examples: http://packtpub.com/article/Using_xtopdf The output will be simple the cells of the tabular data - no formatting. - Vasudev Inspired by nature. - dancingbison.com | @vasudevram | jugad2.blogspot.com On Sat, Apr 20, 2013 at 11:39 PM, Mike Driscoll wrote: > Hi everyone, > > I'm going to go the self-publishing route. Right now, I'm going to focus > on ebooks, although converting it to print would be fun later on. > > - Mike > > > On Sat, Apr 20, 2013 at 12:33 PM, Vasudev Ram wrote: > >> >> IMO, what software you use depends at least to some extent on whether >> you're planning to self-publish it or use some kind of publisher, either >> one of the traditional ones or the online ones. If you use a publisher >> they'll likely have some restrictions about the kinds of software you can >> use to write the book with. If you're publishing yourself, the field is >> wide open, as to the choice of software you use, as long as whatever you >> use meets your needs not only during the writing process, but also during >> the process of creating the final product in different formats - print or >> ebooks - and in ebooks, what formats: PDF, .mobi, EPUB, HTML, etc. >> >> Some options to check out (you may know them already): >> >> - Lulu.com >> >> - Leanpub.com >> >> - Amazon CreateSpace >> >> And there are others. >> >> HTH >> Vasudev >> >> Inspired by nature. >> - dancingbison.com | @vasudevram | jugad2.blogspot.com >> >> >> On Sat, Apr 20, 2013 at 10:54 PM, Naomi Ceder wrote: >> >>> On Sat, Apr 20, 2013 at 12:14 PM, Mike Driscoll wrote: >>> >>>> Hi, >>>> >>>> I keep thinking I need to write a Python book and I think I'm finally >>>> ready to start. Can anyone tell me what software they recommend for writing >>>> the book in? I hate MS Word for writing long documents with markup, but I >>>> don't think Notepad++ really makes sense either. >>>> >>>> Any ideas would be appreciated. Thanks! >>>> >>> >>> For me the choice was largely determined by the publisher's >>> requirements, so I have suffered through using Word (and Open Office, since >>> it crashed less frequently). >>> >>> No useful advice from me, just a caveat. The real pain point I've always >>> felt is keeping code snippets current through testing and revision. I know >>> that some people have been working on solutions to this issue. I can tell >>> you that managing code when writing in something like Word is a total >>> nightmare. >>> >>> >>> >>>> ------------------- >>>> Mike Driscoll >>>> >>>> Blog: http://blog.pythonlibrary.org >>>> >>>> _______________________________________________ >>>> Python-authors mailing list >>>> Python-authors at python.org >>>> http://mail.python.org/mailman/listinfo/python-authors >>>> >>>> >>> >>> >>> -- >>> Naomi Ceder >>> https://plus.google.com/u/0/111396744045017339164/about >>> >>> _______________________________________________ >>> Python-authors mailing list >>> Python-authors at python.org >>> http://mail.python.org/mailman/listinfo/python-authors >>> >>> >> > > > -- > ----------------- > Mike Driscoll > > Blog: http://blog.pythonlibrary.org > > _______________________________________________ > Python-authors mailing list > Python-authors at python.org > http://mail.python.org/mailman/listinfo/python-authors > > -------------- next part -------------- An HTML attachment was scrubbed... URL: From aahz at pythoncraft.com Sun Apr 21 01:50:23 2013 From: aahz at pythoncraft.com (Aahz) Date: Sat, 20 Apr 2013 16:50:23 -0700 Subject: [Python-authors] Book writing software In-Reply-To: References:

Message-ID: <20130420235023.GA7272@panix.com> On Sat, Apr 20, 2013, Naomi Ceder wrote: > > No useful advice from me, just a caveat. The real pain point I've always > felt is keeping code snippets current through testing and revision. I know > that some people have been working on solutions to this issue. I can tell > you that managing code when writing in something like Word is a total > nightmare. This was one of the main reasons I chose reST: I wrote a special include directive that brought in both code and output. (I.e. each example was a separate external file.) -- Aahz (aahz at pythoncraft.com) <*> http://www.pythoncraft.com/ "In theory, there is no difference between theory and practice. But, in practice, there is." --Jan L.A. van de Snepscheut From harry.percival at gmail.com Sun Apr 21 11:36:29 2013 From: harry.percival at gmail.com (Harry Percival) Date: Sun, 21 Apr 2013 10:36:29 +0100 Subject: [Python-authors] Book writing software In-Reply-To: <20130420235023.GA7272@panix.com> References:

<20130420235023.GA7272@panix.com> Message-ID: I'm writing a book for O'Reilly (http://www.obeythetestinggoat.com/), and they recommended AsciiDoc, which I've been really happy with. http://www.methods.co.nz/asciidoc/userguide.html It's a lot like RST or Markdown, but it's designed to convert to docbooks xml as well as html, so it gives you more publishing-specific tools. Another tool I just found out about, which sounds like it could be a useful addition is dexy, which gives you a templating language for including source code listings and command-line output in your doc in an automated way. http://www.dexy.it/ On 21 April 2013 00:50, Aahz wrote: > On Sat, Apr 20, 2013, Naomi Ceder wrote: > > > > No useful advice from me, just a caveat. The real pain point I've always > > felt is keeping code snippets current through testing and revision. I > know > > that some people have been working on solutions to this issue. I can tell > > you that managing code when writing in something like Word is a total > > nightmare. > > This was one of the main reasons I chose reST: I wrote a special include > directive that brought in both code and output. (I.e. each example was > a separate external file.) > -- > Aahz (aahz at pythoncraft.com) <*> > http://www.pythoncraft.com/ > > "In theory, there is no difference between theory and practice. But, in > practice, there is." --Jan L.A. van de Snepscheut > _______________________________________________ > Python-authors mailing list > Python-authors at python.org > http://mail.python.org/mailman/listinfo/python-authors > -- ------------------------------ Harry J.W. Percival ------------------------------ Twitter: @hjwp Mobile: +44 (0) 78877 02511 Skype: harry.percival -------------- next part -------------- An HTML attachment was scrubbed... URL: From regebro at gmail.com Sat Apr 20 21:12:42 2013 From: regebro at gmail.com (Lennart Regebro) Date: Sat, 20 Apr 2013 21:12:42 +0200 Subject: [Python-authors] Book writing software In-Reply-To: <5172DFF7.5000509@ziade.org> References:

<5172DFF7.5000509@ziade.org> Message-ID: On Sat, Apr 20, 2013 at 8:35 PM, Tarek Ziad? wrote: > OTHO LaTex is painful to edit/read compared to reST. IIRC Lennart Regebro > (who I added in CC) did his Python 3 porting book entirely in Rest > so he might have an interesting PoV Yeah, I did it in ReST and output to HTML and PDF via LaTeX. This works well, although you might have to learn a bit too much LaTeX to get the output as you want it. I believe PyDanny and Audrey did the same, and they also output to a couple of eBook formats. In my experience each format you want to support is a significant effort. But that you even *can* support all these formats with Sphinx is a pretty strong argument. It's also super-easy to unit test all your code. Since I needed to support a whole host of Python versions I didn't have my code inline, but in separate external files. But if all your code should run on all the Python versions you support, then you can have the code inline and run tests on it. I'd recommend using Manuel in that case to run the tests. //Lennart From tarek at ziade.org Sat Apr 20 20:35:35 2013 From: tarek at ziade.org (=?ISO-8859-1?Q?Tarek_Ziad=E9?=) Date: Sat, 20 Apr 2013 20:35:35 +0200 Subject: [Python-authors] Book writing software In-Reply-To: References:

Message-ID: <5172DFF7.5000509@ziade.org> On 4/20/13 8:09 PM, Mike Driscoll wrote: > Hi everyone, > > I'm going to go the self-publishing route. Right now, I'm going to > focus on ebooks, although converting it to print would be fun later on. If you want to do a professional rendering I encourage you to use LaTeX. It has all the tools needed to create a book ready to be published, and you can tweak the options to have different sizes/look depending on the target device/print. One anecdote: I used LaTex for one of the book I wrote and it ended up being edited at an editor's. They were able to send it as-is to the printer ! But.. he came back to me all panicked the day after because the pdf did not have the cutting crosses the printer asks (called 'mire' in french) for cutting the pages. All it took me was to add one line to include a LaTex plugin that adds them, and render the PDF again. This would have been impossible with another format like word or reST. OTHO LaTex is painful to edit/read compared to reST. IIRC Lennart Regebro (who I added in CC) did his Python 3 porting book entirely in Rest so he might have an interesting PoV Cheers Tarek -- Tarek Ziad? ? http://ziade.org ? @tarek_ziade From matt at tplus1.com Sun Apr 21 17:29:30 2013 From: matt at tplus1.com (W. Matthew Wilson) Date: Sun, 21 Apr 2013 11:29:30 -0400 Subject: [Python-authors] Book writing software In-Reply-To: References:

<5172DFF7.5000509@ziade.org> Message-ID: Clearly, a bunch of us write with vim + reStructuredText. I'd like to hear about mundane aspects like how did y'all break up the book into separate folders and files, how you did stuff like run your doctests, how you reformat text, any special applications of source control, etc. I've figured out a workflow that I like for when I do talks, and I use a few vim tricks like {gq} to rewrap paragraphs, but I bet I could learn a lot more. Matt On Sat, Apr 20, 2013 at 3:12 PM, Lennart Regebro wrote: > On Sat, Apr 20, 2013 at 8:35 PM, Tarek Ziad? wrote: > > OTHO LaTex is painful to edit/read compared to reST. IIRC Lennart > Regebro > > (who I added in CC) did his Python 3 porting book entirely in Rest > > so he might have an interesting PoV > > Yeah, I did it in ReST and output to HTML and PDF via LaTeX. This > works well, although you might have to learn a bit too much LaTeX to > get the output as you want it. I believe PyDanny and Audrey did the > same, and they also output to a couple of eBook formats. > > In my experience each format you want to support is a significant > effort. But that you even *can* support all these formats with Sphinx > is a pretty strong argument. > It's also super-easy to unit test all your code. Since I needed to > support a whole host of Python versions I didn't have my code inline, > but in separate external files. But if all your code should run on all > the Python versions you support, then you can have the code inline and > run tests on it. I'd recommend using Manuel in that case to run the > tests. > > //Lennart > _______________________________________________ > Python-authors mailing list > Python-authors at python.org > http://mail.python.org/mailman/listinfo/python-authors > -- W. Matthew Wilson matt at tplus1.com http://tplus1.com -------------- next part -------------- An HTML attachment was scrubbed... URL: