Hi Jeff I'm not enthusiastic about the html stuff that you've substituted for the readily available packages. This system requires several edits for any big change to the lyx stuff.
As I've worked with LyX I find it to be a rather good system. I currently publish a couple of books using it and have been able to upgrade those to the latest lyx version available with Ubuntu 8.04. Excuse me for not answering in each section below. I simply am not in tune with your thinking about trashing it and starting over. As for a lot of users, so does LyX. Rayh On Tue, 2008-10-07 at 11:16 -0500, Jeff Epler wrote: > 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 ------------------------------------------------------------------------- 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
