On Fri, 21 May 2004, Kuba Ober wrote:
> Hi,
>
> An idea came to my mind so I feel compelled to share :)
>
> Wouldn't it be nifty to hack the wiki enough to allow it to work on lyx files?
>
> That way we could have wiki-ed lyx user's manual -- I don't think there
> are any projects out there that allow online updating of the manuals.
I've considered using the wiki to let people collaborate on the manuals/
documentation before, but so far I haven't though of a practical solution.
The most feasiable solution at the moment is probably to maintain two sets
of documentation. A "public" version that resides on the wiki, and an
"official" version that's distributed with LyX. Since we haven't seen many
changes in the manual lately, the "synchronization" effort is probably not
too big.
On the other hand, if there is no way to (semi-)automatically convert
between wiki pages and the lyx source of the user's guide, we will
eventually get a fork... actually, a fork might simply arise from the
different forms of the manual, i.e. the fact that one is extremely
hyperlinked (wiki pages) and the other is more like a printed book.
> Since lyx has quite a few users, and sometimes when referring to the
> manual the users come up with small but useful changes, the simplest way
> (from a user's standpoint) would be to have it in a wiki.
It's probably true that the manual would get more changes if it was much
easier for user's to modify them. But I'm not sure we really want to let
random user's edit the manual freely because we loose the QA (for what
it's worth) that we get from the current process (i.e. someone sends in a
patch to the documentation list).
I guess this ends up being a tradeoff between an up-to-date manual and
something where changes are checked thoroughly before being comitted.
Oh, and we shouldn't forget people who are offline (it's of course
possible to save the wiki pages as a local HTML tree using e.g. wget).
> It already does all the change and history tracking for us, essentially
> it would need to be taught some of lyx's ideas about paragraph
> environments and would need to get a TeX previewer which (hopefully) is
> already available for wiki elsewhere.
There's no TeX previewer for wikis AFAIK, but since I don't really
understand what you mean I could be wrong.
In fact, I'm not really sure on how you think this would work. Maybe you
could expand your ideas a bit more?
> In order not to hack the wiki too much, most of existing markup could be
> preserved and lyx-specific things added, necessitating some (hopefully
> non-perl :) wizardry to convert back and forth.
Ah.. you're talking about being able to convert between the two formats.
> I'm thinking of initially supporting only whatever the manual needs,
> i.e. not making it general so that it would work with arbitrary document
> classes. That could be added later if there's demand.
Hmm... expanding on what I think you are suggesting, the user's manual
could be stored as a set of pages in a dedicated group, 'UserGuide'. For
practical reasons, a separate page would be needed that lists all the
pages that comprise the document, 'DocumentComponents'. For the User's
guide, this page would would start with (wiki markup):
* {{Document preamble and title}}
* {{Chapter Introduction}}
** {{Section What is LyX}}
*** {{Subsection Getting Started}}
... and so on
where the page {{Document preamble and title}} would contain (wiki markup):
[=
#LyX 1.3 created this file. For more info see
http://www.lyx.org/
\lyxformat 221
\textclass book
\begin_preamble
\usepackage[english]{babel}
% DO NOT ALTER THIS PREAMBLE!!!!
... and so on until
\end_preamble
\language english
\inputencoding latin1
... etc where the stuff ends with the markup
=]
It should be clear by now that a very simple solution is to write the raw
text from the .lyx file inside quoted 'code-environments' ([=...=]). But
it might be better to introduce a special markup '[[.lyx-begin]]' and
'[[.lyx-end]]'.
Once you have all parts of the user guide entered as wiki pages, it's a
relatively small matter of writing a Php-function that takes pages listed
on 'DocumentComponents' and outputs a .lyx-file. In principle, there could
be a LyX installation on aussie that automatically took this file and
exported a DVI- or PDF-document, thereby allowing for feedback on what the
output looks like.
However, doing this in the reverse direction (i.e. taking a .lyx-file
and automatically splitting it up into several wiki pages, and/or any
speical lyx/wiki-markup) seems quite a bit more difficult to me...
> Side note: I'm *not* volunteering to implement it (not now, at least), unless
> somebody has some marketable and transferable free time, and cheap at that,
> so that I could buy it. Deeds to free time, anyone? ;)
I'm really busy as well at the moment, but I think the idea is worth
discussing. For instance, I'm not sure we really want a user's guide that
is produced in this manner because of the loss of auditing.
/Christian
PS. Personally I think it'd be much more cool if it was possible to import
a wiki page into LyX, edit it and then export it as a wiki page.
--
Christian Ridderström http://www.md.kth.se/~chr
