[lug] Free Linux Authoring Tools?

[Steve Litt]

On Sun, 13 Mar 2016 14:29:15 +0000 (UTC)
stimits at comcast.net wrote:

> Hi,
>  
> I have the need to write a technical document which isn't a full
> book, but which is large enough it could use chapters, index, table
> of contents, so on (a structured document). It would be best if it
> could be exported to PDF, XHTML, plain text, and PostScript. I'm
> looking for authoring tools to do this from Linux. 

I've written 12 books for sale. On 9 of them, I did it on Linux with
Free Software tools. There's no perfect answer to your question, and
you need to consider things in a more detailed manner to reach the
right decision.

First question: Why and how badly do you need XHTML? Do you, or will
you later, need to write ePub? If so, that pretty much rules out LyX.
I'd guess that it rules out TeX too unless you keep your TeX to a very
simple subset.

However, if you can now and in the future keep the requirement to just
PDF, plain text and Postscript, LyX is an outstanding candidate.

> 
> It seems that
> having the document in DocBook XML format would make structuring this
> for all of the different output types practical. There are tools to
> quickly produce any layout I want. The trouble is, I don't want to
> write a hundred pages by manually writing tags and codes, 

Yes. Having to manually write tags slows down authoring considerably,
and often leads to your forgetting the point you wanted to make. There
are some Zencoding editors that make tags easier, but in all cases they
slow you down.

> and would
> really like the table of contents to be dynamically generated based
> on chapters. 

I think every system on the planet writes the TOC (Table of Contents)
based on parts, chapters, sections, subsections etc. That's not a
challenge.

> I have not seen any free editors which could run on
> DocBook code under the covers, while giving a WYSIWYG display for
> whichever style sheet. Me neither.

> Many people have used TeX and family
> for thesis and technical documents, but I suspect this also requires
> knowing the tags and macros (plus I don't think it supports automatic
> generation of a table of contents without writing code). 

I know for a fact that LaTeX supports auto-TOC generation, and suspect
that plain TeX does too. LaTeX is almost worthless if you ever want
your book to be ePub. TeX might work for ePub if you can write a
converter and stick to certain extra-TeX standards when writing it.

> I see Lyx,
> and I like this for simply laying out a page, but it becomes terribly
> manual at times when doing things like vertically centering text for
> a page cover...

The preceding sentence is true, but you lay out that cover exactly
once. If it takes 5 hours to do, who cares: In comparison to the entire
writing project, that's nothing.

Also, if you do LyX right, you go 100% styles based, meaning that
appearance is never applied to text: Instead, appearance is applied to
styles, and the styles are applied to text. This is actually true of
all book authoring.

If you don't need XHTML or ePub, and you do need your books appearance
look exactly how you want it to, LyX is a spectacular tool.

> I'd prefer to mark the text as vertically centered,
> and then let a style sheet conversion decide how to do it (if at
> all). 

That's how LyX does it. Except unless you like LyX' defaults, you'll be
making the stylesheet (called a layout) yourself.

> I could live with seeing plain text in some form of tree
> hierarchy, and then running separate conversion tools for final
> format, such as something half way between an XML code editor and
> plain text. 

Check out the Leo outline processor: http://leoeditor.com/. But take it
from me, Leo isn't simple. If you get Leo to work the way you want it
to, please let me know exactly how you did it so I can do it too.
> 
> Is there any advise anyone can give on Linux tools for
> structured authoring with subsequent conversion to multiple formats?
> Thanks!

In this thread some people have mentioned some lightweight markup
languages like Asciidoctor and Sphinx (there are probably over a dozen
more). These are certainly the least hassle, ***IF*** they do what you
need to do with the appearance you need in the outputs you need. Most
of them are not styles-based: You fingerpaint appearances on text, and
most have no ability to create your own styles, which can be the kiss
of death on some projects. Here are some questions to ask yourself when
considering a lightweight markup language:

* Does it look the way I want on the outputs I require?

* Does it let me create and use my own styles?

* Can it do an index?

* Can it do a bibliography?

* Is it a well-functioning project, or a one man band that could die at
  any time?

Note that, depending on your needs, some of the preceding questions
might be irrelevant for your project.

Researching this answer, I came upon a lightweight markup language,
called Deplate, that allows and encourages you to make your own styles:

http://deplate.sourceforge.net/

However, the project is a one man band, with all that implies for
*your* project.

<rant>
LyX could have completely occupied this space. When making a PDF
document, there's nothing you can't do with LyX, and no set of
appearances and styles you can't implement with LyX. When you start a
PDF-destinationed project with LyX, you know you'll finish it.

But the powers that be in the LyX community have prioritized things
such that, rather than exporting a semantic (X)HTML, they let private
citizens write (X)HTML exporters exporting pidgeon HTML that produces
terrible ePub, and requires huge amounts of human intervention to go to
ePub. They have refused to address this issue, preferring to spend
their time getting LyX to look pristine on Retina displays and
incorporating yet more arcane Ph.D. thesis geegaws.

To add insult to injury, the LyX developers have made their native
format ever more like XML, so human parsability is increasingly
difficult, but they will not make it well formed and valid XML, in
which case it would have  been trivial for me to write a Python XML LyX
to ePub converter.

In summary, if your only output, ever, is PDF or printed page, LyX is
the guaranteed way to get your book written and typeset. But if you
need to also go to ePub, LyX is junk, and due to the community's
priorities, probably always will be.
</rant>

SteveT

Steve Litt 
March 2016 featured book: Quit Joblessness: Start Your Own Business
http://www.troubleshooters.com/startbiz