This message is a bit long, but if you feel you have a stake in the
documentation toolchain (including the file format we use for the docs),
please read and comment. I envision actually doing something about this
issue only after the 2.3 release, so any action is a few months off at a
minimum.
0. What our documentation toolchain should provide
* Can be built on every platform we support
* Creates "printed" format (pdf)
* Creates "onscreen" format (html)
* Can be edited without a lot of difficulty (requiring an old platform
counts as "difficulty"!)
1. Our current toolchain
* Primary documentation "source" format is LyX "format 221",
corresponding to the LyX version on Dapper (the oldest OS we
currently support)
* Converted to PDF by LyX's internal conversion (LyX -> LaTeX -> pdf)
* Converted to HTML by custom software I wrote
* Allows GUI-based editing and discourages hand-editing
2. Problems with the current toolchain
* Cannot easily be edited on post-Dapper systems due to LyX file format
changes
* After editing on a post-Dapper system, "lyx2lyx" can be used to
convert files to "format 221", but this introduces spurious
whitespace changes in lyx source files and I discourage the
practice.
* in some cases, converting from 221 -> 276 (Hardy native format) ->
221 exposes bugs in lyx2lyx that cause it to run forever (seen in
Master_User.lyx among other files)
* Even after we drop Dapper support (which has been promised for emc
2.3 anyway) the HTML conversion software is also unaware of post-221
lyx files
3. The future
If nobody can come up with a good way to resolve the problems created by
LyX file format versioning, then I think it's time to talk about
switching to a different format for documentation.
Here are some things that I am pessimistic about as possibilities:
* Building newer LyX on older supported platforms, so that we can
standardize on newer versions of LyX. I have tried building Hardy's
LyX on dapper, but it gives various obscure errors. (errors that I
have unfortunately deleted instead of saving)
* Building older LyX on newer supported platforms, so that we can
remain standardized on the Dapper version of LyX. This also gives
various obscure errors during the build. I also don't have these
error messages on hand.
* Packaging lyx2lyx (which is a pure Python program) for older
supported platforms, so that we can standardize on newer versions of
LyX. This hits the "infinite loop" bug I mentioned above.
That's why I'm to the point that I want to switch away from LyX. Here
are some alternatives that I can see:
A. Write in LaTeX.
Advantages: LaTeX format won't incompatibly change out from under us.
We can use automated tools to convert LyX to LaTeX.
Disadvantages: No GUI editor; documentation editors (that is, the
people who edit documentation) have to take care to get LaTeX syntax
right. All LaTeX to HTML converters suck.
B. Write in another text-based format such as AsciiDoc or
ReStructuredText (ReST)
Advantages: Formats won't change out from under us, and if they do
these toolchains are likely to be easier than LyX to port to
different OS releases (ReST and AsciiDoc are written in Python, while
LyX is written in C++). We can use automated tools to convert LyX to
ReST. Decent HTML and PDF converters exist for these formats.
Disadvantages: No GUI editor; documentation editors have to take care
to get the format's structure right. We may have to package the
converter software for dapper.
C. Write in an XML-based format such as docbook (yes, I know, XML is
just text)
Advantages: Formats won't change out from under us. We can use
automated tools to convert LyX to docbook. Decent HTML and PDF
converters exist for these formats.
Disadvantages: No GUI editor; documentation editors have to take care
to get the format's structure right. We may have to package the
converter software for dapper. There may be no converter for LyX to
AsciiDoc.
D. Write in OpenOffice or other software using a standard file format
(ODF)
Advntages: Formats won't change out from under us. No need to worry
about getting syntax of a text-based format correct.
Disadvantages: 'cvs diff' is useless. I don't know the state of HTML
conversion in OpenOffice, nor how well it does at editing
multi-hundred-page books. I don't know if it's possible to convert
OpenOffice docs to HTML or PDF without an X server connection, which
is a requirement for the current documentation build system.
E. After 2.3, drop support for Dapper, standardize on Hardy Heron's
LyX file format, and hope that history doesn't repeat itself in the
future. (or if it does, that one of "back-port lyx", "forward port
lyx", or "package lyx2lyx" works the next time)
Advantages: keeps GUI, keeps mostly-plain-text format
Disadvantages: requires our custom HTML converter to be updated to
the new LyX format. May require packaging that we package LyX or
lyx2lyx at some future date. May require too much optimism.
All of these options have the drawback that they break revision history
with the old documentation.
Personally, I'd go for option B. Both AsciiDoc and ReST have a lot of
users. In particular I recently learned that the Python project
transitioned from LaTeX to ReST for all their documentation. Their
HTML and PDF documentation look better than ever, while the source code
is also very readable as plain text. Here's one short example (this is the
*source code* for the documentation, not a file that it produces as output!):
**********************************
An Informal Introduction to Python
**********************************
In the following examples, input and output are distinguished by the
presence or
absence of prompts (``>>>`` and ``...``): to repeat the example, you must
type
everything after the prompt, when the prompt appears; lines that do not
begin
with a prompt are output from the interpreter. Note that a secondary prompt
on a
line by itself in an example means you must type a blank line; this is used
to
end a multi-line command.
...
Some examples::
# this is the first comment
SPAM = 1 # and this is the second comment
# ... and now a third!
STRING = "# This is not a comment."
the HTML can be seen at
http://www.python.org/doc/2.6/tutorial/introduction.html
Options A and C are a lot like option B, but I don't think they offer
any important advantages. My impression is that AsciiDoc and ReST are
both easier to write than LaTeX or XML, though this may just be my bias
showing.
I really don't like option D; I include it because some find it
preferable to have a GUI editor. I think that losing useful diffs,
commandline greps, and the ability to make trivial typo fixes without
firing up a big application are drawbacks that are simply too big to
be overcome by the "it has a gui" advantage.
Likewise, I don't like option E much. It feels like betting on a losing
horse twice.
Thoughts?
Jeff
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Emc-developers mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/emc-developers
