Re: please consolidate the documentation

[Stephen Harris]

Helge Hafting wrote:

On Fri, Jul 21, 2006 at 12:08:48AM +1000, John Pye wrote:



I don't think that we should expect people to use LyX as their
documentation browser.




Sure, LyX is not  my choice for a browser.  But documentation
for LyX itself is a special case, see below:




Operating systems all provide good standard ways
of accessing help: Installed LyX documentation should play nice with
those so that there's one less thing for new users to learn. 




Well, supplying LyX docs in pdf and html is nice, of course.
Still, the main format for LyX documentation must be LyX files.
LyX is supposed to be a document processor good for just this sort
of documents, so using anything else would show a worrisome lack
of confidence in our own software.  The User's Guide is a nice showcase
for what can be done with LyX, and it is a quick demonstration of
how well LyX handles long documents.  (It is quite a few pages, and
for demonstration purposes, try copy-pasting the entire thing
several times . . . no crash.)

Helge Hafting



I can't imagine first writing LyX documentation in any other format
than .lyx. Most people don't read the docs first, but turn to them
when they need to find solutions. So suppose they want to know what
the User's Guide has to say about "margins". Do you think that the
LyX: Find & Replace has been designed for the purpose of finding
information for solving problems or as an editing tool? The .pdf
format doesn't normally allow editing of the content so searching
is designed for finding keywords to solve problems with a more
evolved interface. Because LyX can serve in this capacity doesn't
mean it is optimal in comparison to a tool made for this purpose.
I think a fair estimate is that the documentation is initially
read by people who have not learned that it is cost effective to
read the documentation first, and that a huge majority of users
will be reading and searching for keywords while troubleshooting.

I think the strength of LyX is that it can convert from the .lyx
format to *other* user preferred formats which might have small
features like a magnifying glass for reading the small print of
a diagram, which isn't (AFAIK) included in LyX because it has so
little application to the focus of LyX. The Windows LyX display
is only about 90-95% of the quality of LyX displayed on Linux
or Cygwin, which is another small reason to convert it to a
format that maintains quality equality for longer readings.

It can be said that a user could glean some information by
inspecting the structure of a LyX guide self-referentially
gathering some visual clues. This seems to be a strength of
using LyX for reading documentation when compared to a pdf
reader. But if you compare LyX to the Visual FAQ by Scott
Pakin, tug.ctan.org/tex-archive/info/visualFAQ/ , you will
see a tool designed for a function LyX stretches to fill.

LyX is like a pair of pliers that can be pressed into doing
the job extemes of a couple of different size wrenches like
the Visual FAQ, and Reader with its advanced search options.

> LyX is supposed to be a document processor good for just this sort
> of documents, so using anything else would show a worrisome lack
> of confidence in our own software.

I think the claim that Lyx is the best tool for creating help
guides etc. is not the same claim as that LyX is the best tool
for reading such documents it creates, and matches or surpasses
a mature pdf reader which is dedicated to displaying and searches.

The subject: please consolidate the documentation, is I think
motivated by difficulty in finding a solution to some problem.
If the Wiki were converted to one huge .lyx file, I doubt that
it would be that helpful, though you could do time consuming
searches for some keyword, if the user knew the right keyword.
Building a faster internal storage of keywords found on the
Wiki will not be so useful to the new user, but will more serve
the experienced user who knows what concept to look for.

So a detailed back of the book type index is in a more usable
format than a list of words and their locations produced by
the search engine and it is also a faster search. The new user
perusing such an index replete with "see" and "see also" opens
the door for a serendipitous juxtaposition of chance into design.
A few shorter LyX visual faqs, each covering some major topic,
with the potential of being merged later, would stifle any
complaints about inadequate documentation being too spread out.

If wishes were horses, beggars would ride (wishlist),
Stephen

Re: please consolidate the documentation

[Helge Hafting]

On Fri, Jul 21, 2006 at 12:08:48AM +1000, John Pye wrote:
> Hi all,
> 
> I'd like to say congratulations to all on the re-inauguration of the LyX
> documentation team ;-) ! The scattered documentation of LyX has
> frustrated me too. I have some thoughts and ideas to mention...
>
[...]
> I don't think that we should expect people to use LyX as their
> documentation browser. 
Sure, LyX is not  my choice for a browser.  But documentation
for LyX itself is a special case, see below:

> Operating systems all provide good standard ways
> of accessing help: Installed LyX documentation should play nice with
> those so that there's one less thing for new users to learn. I think
> that the LyX manual should serve as a model example of a well-published
> document, with HTML and PDF versions, downloadable in various formats,
> etc. It should be the type of end-result document that a person setting
> out to write a book or a software manunal with LyX would aspire to
> produce, not an exposition of the LyX GUI.
> 
Well, supplying LyX docs in pdf and html is nice, of course.
Still, the main format for LyX documentation must be LyX files.
LyX is supposed to be a document processor good for just this sort
of documents, so using anything else would show a worrisome lack
of confidence in our own software.  The User's Guide is a nice showcase
for what can be done with LyX, and it is a quick demonstration of
how well LyX handles long documents.  (It is quite a few pages, and
for demonstration purposes, try copy-pasting the entire thing
several times . . . no crash.)

Also, when users see something 'cool' in the User's Guide, they
can cut & paste it directly from the LyX file, which gets them going
quickly.


> There should be a good self-updating HTML version of the LyX manual.
> Ideally a local search engine could be installed that would search both
> the HTML manual and the Wiki side-by-side with a single installation of
> lucene, xapian, swish-e, etc.
>
Cool, but can you make this work on all the very different platforms 
that runs LyX?  A search engine on the web might be easier to pull off.
And of course one should be able to use LyX on a machine that
not necessarily have a web browser at all.

> We should aspire to the PDF version of the manual being a last port of
> call: online searching, CHM, Yelp (under GNOME), etc should be able to
> provide nicer and more efficient ways to read and search. Although,
> given what LyX is, it's important to produce a good looking PDF to prove
> what LyX can do.
> 
> We're meanwhile trying to use LyX for documenting a project I've worked
> on: the ASCEND modelling environment. So we're very interested in taking
> the right approach here. I'm sure a lot of other writers, especially of
> software documentation, must be as well.
> 
The right approach for software documentation depends a lot of
the intended users, the platform, and other aspects of the environment
in which the software will be used.  The perfect approach for one
project may therefore be wrong for another.

Helge Hafting

Re: please consolidate the documentation

[Stephen Harris]

John Pye wrote:

Hi all,

I'd like to say congratulations to all on the re-inauguration of the LyX
documentation team ;-) ! The scattered documentation of LyX has
frustrated me too. I have some thoughts and ideas to mention...

First, I think that the shining example of the *delivery* of software
documentation is the PHP manual, which is at http://www.php.net/manual/en/.



SH: It seems good to me and other people hold it as an example.


In its favour: anyone can annotate a page in the manual with their own
tips and clarifications. This is great and it prevents quite the same
degree of random organic growth that occurs when people feel that they
should jot things into a wiki. I would imagine it makes things easier
for editors too: the community tells you where information is missing or
unclear. Here is an example of an annotated page:
http://au.php.net/manual/en/function.array-sum.php



This is my concern about the Wiki method too. When discussing what
is good for LyX one needs to factor in the available resources.
A limited number of developers already committed to high priority 
projects, no dedicated Editor, and a small documentation team.



Perhaps a limitation of the PHP manual's user-notes feature is that
whole new pages are hard for people to add. So there's still a place for
Wiki but it shouldn't be one of the primary resources, I don't think.

The PHP people have also done a great job of providing translations of
their manual, and also provide the documentation in lots of different
formats, eg CHM for reading online with Windows, and online/offline HTML
and PDF, eg see http://au.php.net/docs.php. There is a Linux
documentation format standard over at freedesktop.org that we should
comply with too.



I think these ideas serve a much larger project with much greater
resources. LyX is cross-platform itself. It is readable in DVI,
Postscript and pdf. The conversion to html is straightforward
and XML is the next LyX major goal. "htlatex foo.tex" -> foo.html

The problem with OS specific documentation is that it is only
going to benefit about ~half of the users at most, and they
already have several formats available. The left margin toc
is perhaps slightly better/readable for chm than pdf but I
don't know of a free .tex or .pdf converter to .chm. Problems
with .chm or say kde are outside the scope of LyX and only
benefit about half the users. LyX doesn't have a reource luxury.


I don't think that we should expect people to use LyX as their
documentation browser. Operating systems all provide good standard ways
of accessing help: Installed LyX documentation should play nice with
those so that there's one less thing for new users to learn. I think
that the LyX manual should serve as a model example of a well-published
document, with HTML and PDF versions, downloadable in various formats,
etc. It should be the type of end-result document that a person setting
out to write a book or a software manunal with LyX would aspire to
produce, not an exposition of the LyX GUI.



I certainly agree, showcase comes to mind. The exposition of
the Lyx GUI could be done like the Latex Visual FAQ, the LyX
Visual FAQ. One person produced this remarkable package!


There should be a good self-updating HTML version of the LyX manual.
Ideally a local search engine could be installed that would search both
the HTML manual and the Wiki side-by-side with a single installation of
lucene, xapian, swish-e, etc.



As I understand it, this will work better with XML. Updating
comes to mind also with the Wiki index project (searchindex).


We should aspire to the PDF version of the manual being a last port of
call: online searching, CHM, Yelp (under GNOME), etc should be able to
provide nicer and more efficient ways to read and search. Although,
given what LyX is, it's important to produce a good looking PDF to prove
what LyX can do.



It took me less than 3 minutes to convert those 4 LyX guides which
come with LyX-Help into pdfs and combine them into 1 searchable file.
How long to convert those 4 .lyx files and combine them into 1 .chm
with the left margin toc or then without it? How about Yelp?



We're meanwhile trying to use LyX for documenting a project I've worked
on: the ASCEND modelling environment. So we're very interested in taking
the right approach here. I'm sure a lot of other writers, especially of
software documentation, must be as well.

Cheers
JP



I would like to the LyX Wiki displayed like a book.
Wolfram does a great job of indexing, here is an
online, hyperlinked, searchable index:

http://www.wolframscience.com/nksonline/page-852d-text
General Note/Intro to the Index

http://www.wolframscience.com/nksonline/toc.html
the toc which links to the index

http://www.wolframscience.com/nksonline/index/

I am not as experienced as you are with the nitty gritty.
But I am a good judge of books and their indexes. (ices)
Wolfram's "A New Kind of Science" is over 1200 pages
long. And if you are exploring a topic like

Re: please consolidate the documentation

[Stephen Harris]

Jean-Pierre Chretien wrote:

Date: Thu, 20 Jul 2006 03:05:50 -0700
To: Jean-Pierre Chretien <[EMAIL PROTECTED]>
CC: lyx-users@lists.lyx.org
Subject: Re: please consolidate the documentation
From: Stephen Harris <[EMAIL PROTECTED]>

[...]

swish-e is supposed to be capable of indexing a Wiki.
Perhaps this categorizing scheme will be quite productive.


PmWiki includes it own indexing scheme: the search field in 
each page is able to retrieve match in wiki pages.


swish-e (or similar, htdig e.g.) are useful for segmented 

> HTML publication indexing.





I am under the impression that the indexing you speak of
just accelerates PmWikis normal searchbox function which
doesn't include the content of the pdf files on the Wiki?
I'm thinking that the PmWiki indexing scheme will report
text Wiki matches of say "layout" but not .pdf content?
That is the reason behind tagging pages with categories?

swish-e will index pdf files on the wiki and the wiki. I
would like to see a complete file, visually, like a TOC.

The purpose behind the Index was to benefit inexperienced
users who did not already know the keyword needed for the
search; making the Wiki more accessible for new users.

Precompiled special searchindex files don't do that, they
make it faster, but do not include new content-- meaning
something not available to you if you already know the
right keyword, using the normal search function. Indexing
pdf files provides new content, keywords are listed from
a new domain. I didn't get the idea that the Pmwiki index
would include "see also"(s). Increasing internet exposure
had no priority so perhaps you developed the index idea
for the Wiki, independently of the categorization origin.

Regards,
Stephen

Re: please consolidate the documentation

[John Pye]

Hi all,

I'd like to say congratulations to all on the re-inauguration of the LyX
documentation team ;-) ! The scattered documentation of LyX has
frustrated me too. I have some thoughts and ideas to mention...

First, I think that the shining example of the *delivery* of software
documentation is the PHP manual, which is at http://www.php.net/manual/en/.

In its favour: anyone can annotate a page in the manual with their own
tips and clarifications. This is great and it prevents quite the same
degree of random organic growth that occurs when people feel that they
should jot things into a wiki. I would imagine it makes things easier
for editors too: the community tells you where information is missing or
unclear. Here is an example of an annotated page:
http://au.php.net/manual/en/function.array-sum.php

Perhaps a limitation of the PHP manual's user-notes feature is that
whole new pages are hard for people to add. So there's still a place for
Wiki but it shouldn't be one of the primary resources, I don't think.

The PHP people have also done a great job of providing translations of
their manual, and also provide the documentation in lots of different
formats, eg CHM for reading online with Windows, and online/offline HTML
and PDF, eg see http://au.php.net/docs.php. There is a Linux
documentation format standard over at freedesktop.org that we should
comply with too.

I don't think that we should expect people to use LyX as their
documentation browser. Operating systems all provide good standard ways
of accessing help: Installed LyX documentation should play nice with
those so that there's one less thing for new users to learn. I think
that the LyX manual should serve as a model example of a well-published
document, with HTML and PDF versions, downloadable in various formats,
etc. It should be the type of end-result document that a person setting
out to write a book or a software manunal with LyX would aspire to
produce, not an exposition of the LyX GUI.

There should be a good self-updating HTML version of the LyX manual.
Ideally a local search engine could be installed that would search both
the HTML manual and the Wiki side-by-side with a single installation of
lucene, xapian, swish-e, etc.

We should aspire to the PDF version of the manual being a last port of
call: online searching, CHM, Yelp (under GNOME), etc should be able to
provide nicer and more efficient ways to read and search. Although,
given what LyX is, it's important to produce a good looking PDF to prove
what LyX can do.

We're meanwhile trying to use LyX for documenting a project I've worked
on: the ASCEND modelling environment. So we're very interested in taking
the right approach here. I'm sure a lot of other writers, especially of
software documentation, must be as well.

Cheers
JP

Jean-Pierre Chretien wrote:

>>>Date: Thu, 20 Jul 2006 03:05:50 -0700
>>>To: Jean-Pierre Chretien <[EMAIL PROTECTED]>
>>>CC: lyx-users@lists.lyx.org
>>>Subject: Re: please consolidate the documentation
>>>From: Stephen Harris <[EMAIL PROTECTED]>
>>>  
>>>
>[...]
>  
>
>>>swish-e is supposed to be capable of indexing a Wiki.
>>>Perhaps this categorizing scheme will be quite productive.
>>>  
>>>
>
>PmWiki includes it own indexing scheme: the search field in each page is able 
>to retrieve
>match in wiki pages.
>
>swish-e (or similar, htdig e.g.) are useful for segmented HTML publication 
>indexing.
>
>  
>

Re: please consolidate the documentation

[Jean-Pierre Chretien]

>>Date: Thu, 20 Jul 2006 03:05:50 -0700
>>To: Jean-Pierre Chretien <[EMAIL PROTECTED]>
>>CC: lyx-users@lists.lyx.org
>>Subject: Re: please consolidate the documentation
>>From: Stephen Harris <[EMAIL PROTECTED]>
[...]
>>
>>swish-e is supposed to be capable of indexing a Wiki.
>>Perhaps this categorizing scheme will be quite productive.

PmWiki includes it own indexing scheme: the search field in each page is able 
to retrieve
match in wiki pages.

swish-e (or similar, htdig e.g.) are useful for segmented HTML publication 
indexing.

-- 
Jean-Pierre

Re: please consolidate the documentation

[Stephen Harris]

Jean-Pierre Chretien wrote:

Date: Wed, 19 Jul 2006 09:37:55 -0700
To: lyx-users@lists.lyx.org
Subject: Re: please consolidate the documentation
From: Stephen Harris <[EMAIL PROTECTED]>

Ingo Klöcker wrote:

Am Mittwoch, 19. Juli 2006 08:58 schrieb Martin A. Hansen:

[...]
In any case, I'm pretty sure we can discuss this to death. Some people 
prefer a several megabyte large HTML file and other people prefer the 
same information nicely split up into several HTML files per chapter or 
even section (with nice navigation buttons of course). While the first 
approach is only feasible for people with a fast internet connection 
the second approach is feasible for anyone.


There used to be a splitted HTML version of the doc.
I found this while googling for "lyx verbatim 1.4" :-)
http://www.lyx.org/~jug/lyx/lyxdoc/Extended/node6.html
It's lyx-1.1.6 apparently, 1.4 is the section number.

The toc is here:
http://www.lyx.org/~jug/lyx/lyxdoc

However a local indexing is needed (btw, lyx.org does not seem to be indexed) 
as googling
retrieves a lot of noise.

Turning the doc into a wiki seems complicated, as only two levels are allowed, 
but maybe there are
tools to do so ? The indexing problem is solved this way.




Wolfram's indexes are very detailed and I like the
hyperlink feature but I suppose that requires html.
http://documents.wolfram.com/v4/MainBook/Index/

This webpage index shows the 'see also' feature.
For instance "layouts" would probably have several 'see alsos'
and also appear in several references ->each given a short code,
which could be listed alphabetically with page numbers. I want
it to be detailed enough to provide clues to inexperienced users.
http://www.indexers.org.uk/site/index.htm

swish-e is supposed to be capable of indexing a Wiki.
Perhaps this categorizing scheme will be quite productive.

Regards,
Stephen


If layouts were mentioned in several documents

Re: please consolidate the documentation

[Jean-Pierre Chretien]

>>Date: Wed, 19 Jul 2006 09:37:55 -0700
>>To: lyx-users@lists.lyx.org
>>Subject: Re: please consolidate the documentation
>>From: Stephen Harris <[EMAIL PROTECTED]>
>>
>>Ingo Klöcker wrote:
>>> Am Mittwoch, 19. Juli 2006 08:58 schrieb Martin A. Hansen:
>>
[...]
>>> 
>>> In any case, I'm pretty sure we can discuss this to death. Some people 
>>> prefer a several megabyte large HTML file and other people prefer the 
>>> same information nicely split up into several HTML files per chapter or 
>>> even section (with nice navigation buttons of course). While the first 
>>> approach is only feasible for people with a fast internet connection 
>>> the second approach is feasible for anyone.

There used to be a splitted HTML version of the doc.
I found this while googling for "lyx verbatim 1.4" :-)
http://www.lyx.org/~jug/lyx/lyxdoc/Extended/node6.html
It's lyx-1.1.6 apparently, 1.4 is the section number.

The toc is here:
http://www.lyx.org/~jug/lyx/lyxdoc

However a local indexing is needed (btw, lyx.org does not seem to be indexed) 
as googling
retrieves a lot of noise.

Turning the doc into a wiki seems complicated, as only two levels are allowed, 
but maybe there are
tools to do so ? The indexing problem is solved this way.

-- 
Jean-Pierre

Re: please consolidate the documentation

[Stephen Harris]

Ingo Klöcker wrote:

Am Mittwoch, 19. Juli 2006 08:58 schrieb Martin A. Hansen:


So what is the typical use-case for the LyX Manual? That someone wants 
to read it from the first page to the last page? Or that someone wants 
to read about a specific subject, say including graphics?


In my experience the latter is the way more common use-case. I've read 
the Introduction once and the Tutorial once. And now, every now and 
then, I open the other two documents because I want to look something 
up. Therefore it would be preferable if loading the part I'm interested 
in wouldn't take 10 seconds but only 1 second. The only way to achieve 
this is to split up the document. Of course, there should be a master 
document with a complete toc so that I can quickly navigate to the 
chapter I'm interested in. Ideally, for the user it wouldn't feel 
different from one large lyx file with the exception that loading would 
be magnitudes faster.


In any case, I'm pretty sure we can discuss this to death. Some people 
prefer a several megabyte large HTML file and other people prefer the 
same information nicely split up into several HTML files per chapter or 
even section (with nice navigation buttons of course). While the first 
approach is only feasible for people with a fast internet connection 
the second approach is feasible for anyone.


And as always there's the option to do both. Provide the LyX manual as 
one huge single file and additionally split up into several files. I'd 
put the multiple-files version into the release and put the URL of the 
single file version near the start of the multiple-files version.





Regards,
Ingo



I wasn't so sure that consolidated Help guides were all that useful.
But making one in .pdf format and one in .lyx format to satisfy those 
who wanted it wasn't all that hard, so why not. It's on the Wiki.

There are people who don't enjoy discussing things and they tend to
describe the people who do enjoy it as "beating a good horse to death".
Single .lyx help guides already exist and it is pretty easy to pdflatex
a pdf version from Lyx and there are existing multiple .lyx/pdf guides
it doesn't seem fruitful to debate preferences.

Learning visually brings to mind the Visual FAQ which demonstrates
how to do something on the page itself and links to the tug FAQ.

http://www.tug.org/tex-archive/info/visualFAQ/
"Having trouble finding the answer to a LaTeX question?  The Visual
LaTeX FAQ is an innovative new search interface that presents over a
hundred typeset samples of frequently requested document formatting.
Simply click on a hyperlinked piece of text and the Visual LaTeX FAQ
will send your Web browser to the appropriate page in the UK TeX FAQ."

SH: I think a LyX VisualFAQ is a possible Wiki documentation project.

Ingo: Of course, there should be a master document with a complete
toc so that I can quickly navigate to the chapter I'm interested in.

SH: The problem with keyword searches is that you have to know the
keyword. We could create a detailed cross-referenced index of the
entire Wiki which would be similar to the ouput of several hundred
keyword searches. This master index would point to the document(s)
which contained the concept being researched or related ideas. One
wouldn't have to wade through several documents to find the right
one. The way it is now, "layouts" might produce 12 hits, but which
one of the 12 should be prioritized in your reading? A detailed
index incorporates a meta-toc.

Such a document would also be useful for building the Visual LyX
FAQ. It would inform the FAQ as to which document informs the
reader in more detail about a particular process by a hyperlink
to the doc and/or the Index. This treats the whole Wiki as a FAQ.
The index would also point to duplicate entries needing editing or 
possible deletion in an effort to become systematically sectioned

when dividing the whole into assigned parts for a group undertaking.

People don't all learn the same way,
Stephen

Re: please consolidate the documentation

[Ingo Klöcker]

Am Mittwoch, 19. Juli 2006 08:58 schrieb Martin A. Hansen:
> once again -> pdf files are for printing and reading - not for
> reading online. printing the documentation may give you a nice book
> to keep under the pillow, but it prevents you from seeing how lyx
> formatting is done, using cross refereces etc. and i think that lyx
> is an extremely nice "editor" to read docs online!
>
> if you loose the overview of a single lyx document - then it is badly
> structured IMHO.
>
> if a single lyx document is too heavy for some machines i would say
> that is a major problem. will an equivalent latex file be as heavy,
> or is this a lyx specific thing?

Even if a single lyx file is not too heavy loading the document will 
still be proportional to the file size.

So what is the typical use-case for the LyX Manual? That someone wants 
to read it from the first page to the last page? Or that someone wants 
to read about a specific subject, say including graphics?

In my experience the latter is the way more common use-case. I've read 
the Introduction once and the Tutorial once. And now, every now and 
then, I open the other two documents because I want to look something 
up. Therefore it would be preferable if loading the part I'm interested 
in wouldn't take 10 seconds but only 1 second. The only way to achieve 
this is to split up the document. Of course, there should be a master 
document with a complete toc so that I can quickly navigate to the 
chapter I'm interested in. Ideally, for the user it wouldn't feel 
different from one large lyx file with the exception that loading would 
be magnitudes faster.

In any case, I'm pretty sure we can discuss this to death. Some people 
prefer a several megabyte large HTML file and other people prefer the 
same information nicely split up into several HTML files per chapter or 
even section (with nice navigation buttons of course). While the first 
approach is only feasible for people with a fast internet connection 
the second approach is feasible for anyone.

And as always there's the option to do both. Provide the LyX manual as 
one huge single file and additionally split up into several files. I'd 
put the multiple-files version into the release and put the URL of the 
single file version near the start of the multiple-files version.

And BTW, Martin, since you want to read the documentation in LyX in 
order to see how lyx formatting is done, I don't understand why you 
want to deny the users to see how they can create a document consisting 
of multiple lyx files. By creating one huge file you'd lose the chance 
to demonstrate this feature of LyX/LaTeX.

Regards,
Ingo


pgpF3BqkO4t4T.pgp
Description: PGP signature

Re: please consolidate the documentation

[Martin A. Hansen]

once again -> pdf files are for printing and reading - not for reading
online. printing the documentation may give you a nice book to keep under
the pillow, but it prevents you from seeing how lyx formatting is done,
using cross refereces etc. and i think that lyx is an extremely nice
"editor" to read docs online!

if you loose the overview of a single lyx document - then it is badly
structured IMHO.

if a single lyx document is too heavy for some machines i would say that is
a major problem. will an equivalent latex file be as heavy, or is this a lyx
specific thing?


martin




On 7/18/06, Uwe Stöhr <[EMAIL PROTECTED]> wrote:


Sven Schreiber schrieb:

> Well isn't there a documentation team?

Unfortunately there is no team. At the moment the developers add new
docs sections if they implemented a new feature. Therefore the docs
aren't consistent in style and not always well verbalized.
The last time I cleaned up the docs a bit was in 2004. In the meantime I
started to work on a big docs update but haven't the time to do this all
alone.

Please have a look at this wiki page I created as base for the docs
cleanup/consolidation:

http://wiki.lyx.org/LyX/DocumentationDevelopment

The docs you'll find there contains lots of improvements and should be
the base for further work on the docs. They are not up to date for LyX
1.4 but this should be done quickly.

The general wiki docs category is

http://wiki.lyx.org/LyX/Documentation

where Christian Ridderström just uploaded a merged docs file.

Just for the info, under

http://wiki.lyx.org/LyX/Tables
and
http://wiki.lyx.org/LyX/LyXMathebefehle

are some Wiki-pages I created. Their content should be part of further
docs.

> Maybe they don't think it's a good idea?
> What would be the recommended way of making a concrete
> proposal, attach the resulting single lyx file to a message on this
list?

One of my docs goals is to be able to print a LyX-book, like the books
of the series from Dante, the german TeX-users group. Therefore a single
documentation file as printable PDF is a good idea but not a single
LyX-file!
The reason is in one hand the performance: LyX consumes a lot of system
power to handle large files so that some users might have problems when
they want to use the documentation online within LyX.
On the other hand and this is the real problem: You'll loose the
overview to keep the docs up to date. I spent a lot of time to update
the docs to tell you that even the current userguide.lyx is too big for
a single file.
I propose to have a LyX-file for each chapter and a master LyX-file
where they are included. If you run the master through pdflatex you'll
get a nice all in one PDF as you wanted. The small LyX-files helps you
to reduce the compiling time for PDF or DVI if you work on a chapter.
That's the way books are written.

I hope I've written to a new docs team member. I would be very happy if
yes.

regards Uwe

Re: please consolidate the documentation

[Uwe Stöhr]

Sven Schreiber schrieb:


Well isn't there a documentation team?


Unfortunately there is no team. At the moment the developers add new 
docs sections if they implemented a new feature. Therefore the docs 
aren't consistent in style and not always well verbalized.
The last time I cleaned up the docs a bit was in 2004. In the meantime I 
started to work on a big docs update but haven't the time to do this all 
alone.


Please have a look at this wiki page I created as base for the docs 
cleanup/consolidation:


http://wiki.lyx.org/LyX/DocumentationDevelopment

The docs you'll find there contains lots of improvements and should be 
the base for further work on the docs. They are not up to date for LyX 
1.4 but this should be done quickly.


The general wiki docs category is

http://wiki.lyx.org/LyX/Documentation

where Christian Ridderström just uploaded a merged docs file.

Just for the info, under

http://wiki.lyx.org/LyX/Tables
and
http://wiki.lyx.org/LyX/LyXMathebefehle

are some Wiki-pages I created. Their content should be part of further docs.


Maybe they don't think it's a good idea?
What would be the recommended way of making a concrete
proposal, attach the resulting single lyx file to a message on this list?


One of my docs goals is to be able to print a LyX-book, like the books 
of the series from Dante, the german TeX-users group. Therefore a single 
documentation file as printable PDF is a good idea but not a single 
LyX-file!
The reason is in one hand the performance: LyX consumes a lot of system 
power to handle large files so that some users might have problems when 
they want to use the documentation online within LyX.
On the other hand and this is the real problem: You'll loose the 
overview to keep the docs up to date. I spent a lot of time to update 
the docs to tell you that even the current userguide.lyx is too big for 
a single file.
I propose to have a LyX-file for each chapter and a master LyX-file 
where they are included. If you run the master through pdflatex you'll 
get a nice all in one PDF as you wanted. The small LyX-files helps you 
to reduce the compiling time for PDF or DVI if you work on a chapter. 
That's the way books are written.


I hope I've written to a new docs team member. I would be very happy if yes.

regards Uwe

Re: please consolidate the documentation

[Lorenzo Paulatto]

Daniel Watkins ha scritto:
> Sven Schreiber wrote:
>>> So please consolidate the documentation into one file (or let me do it).
> 
> I promise you, no-one here is going to hold you back, if you're
> volunteering[*]. :p

There is a problem you may have missed: in some languages (italian at
least) only the user manual has been translated, while the extended
features haven't. It would be really odd to have a mixed language document.

As far as I can stand it I think it would confuse many people.

Bye

-- 
Lorenzo `paulatz' Paulatto
Trieste

``Grandissima mi par l'inezia di coloro che vorrebbero che Iddio avesse
fatto l'universo più proporzionato alla piccola capacità del lor discorso.''
 --Galileo Galilei (Opere VII)

 

 

 --

 Email.it, the professional e-mail, gratis per te: http://www.email.it/f

 

 Sponsor:

 Le speciali Offerte di Benvenuto di Cassine di Pietra:

* scopra il gusto ed i vantaggi delle tradizioni contadine

* 

 Clicca qui: http://adv.email.it/cgi-bin/foclick.cgi?mid=3924&d=18-7

Re: please consolidate the documentation

[Sven Schreiber]

[EMAIL PROTECTED] schrieb:
> On Tue, 18 Jul 2006, Sven Schreiber wrote:
> 
>> Yes, easily getting an overview of what's in the help file.
> 
> Good point. To summarize:
> 
> * We'd like an overview of what's in all the help files. Perhaps some
>   kind of table of contents for the whole thing.
> 
> * We'd like to be able to search all the help files in one go.
> 
> * We'd like to be able to have cross-links between help files.
> 
> And one suggestion for fixing these problems is merging the help
> documents. Is this about it?

Yes, afaics.


> Does it have to be in a .lyx-file?
> 
> Would a single PDF be ok with you?
> 
> Or would it be useful if it was in HTML?

I don't care too much about the format.


> What if we can come with a way that let's us keep the official
> documentation partitioned as it is, but have it automatically be merged
> into a single document for users such as yourself?
>

If that's the way of least resistance, fine. However, I simply don't see
why it's so much easier to maintain a separate document (with references
to other docs!) than to maintain a part of a book. Also, file sizes may
be still an issue, but not as much as back in the 90s.

As I said, I'd be satisfied with merging just the user guide and
extended features. That really cannot be a big deal, right?

-sven

Re: please consolidate the documentation

[Jean-Pierre Chretien]

>>To: lyx-users@lists.lyx.org
>>From: [EMAIL PROTECTED]
>>Subject: Re: please consolidate the documentation
>>Date: Tue, 18 Jul 2006 15:24:33 +0200
>>X-X-Sender: [EMAIL PROTECTED]
>>
>>On Tue, 18 Jul 2006, Sven Schreiber wrote:
>>
>>> Yes, easily getting an overview of what's in the help file.
>>
>>Good point. To summarize:
>>
>>* We'd like an overview of what's in all the help files. Perhaps some
>>   kind of table of contents for the whole thing.
>>
>>* We'd like to be able to search all the help files in one go.

See below, HTML or PDF versions.

>>
>>* We'd like to be able to have cross-links between help files.

This one already exists, try Alt-H a

>>
>>And one suggestion for fixing these problems is merging the help 
>>documents. Is this about it?

As far as PDF or index/search is considered, this is not needed.

>>
>>> I have this obsession with getting the big picture. Keyword search isn't 
>>> everything, as many long google hours have tought all of us, right? And 
>>> I mean on-screen, I can't carry around a printout.
>>
>>Does it have to be in a .lyx-file?
>>
>>Would a single PDF be ok with you?
>>
>>Or would it be useful if it was in HTML?

Some years ago, to encourage LyX use, I built a set of HTML files using 
latex2html
and maximum depth in split, and gave intranet index access to it.
This has some drawbacks wrt LyX access as some illustrations can only be seen 
with LyX.
Advantage is piecewise access to information, prone to internet access even 
with a slow connection.
I sill must have the script somewhere... 

>>
>>> As you know, Lyx is pretty bad at handling multiple open documents, 
>>> which contributes to my desire to have only one relevant file.
>>
>>To be honest, it was three years since I wrote anything big using LyX. But 
>>then I didn't find it that difficult using multi-part documents. Maybe my 
>>expectations were low.

I use multipart often, works great (but I don't need crossrefs between parts).

Just my 5c...

-- 
Jean-Pierre

Re: please consolidate the documentation

[christian . ridderstrom]

On Tue, 18 Jul 2006, Sven Schreiber wrote:


Yes, easily getting an overview of what's in the help file.


Good point. To summarize:

* We'd like an overview of what's in all the help files. Perhaps some
  kind of table of contents for the whole thing.

* We'd like to be able to search all the help files in one go.

* We'd like to be able to have cross-links between help files.

And one suggestion for fixing these problems is merging the help 
documents. Is this about it?


I have this obsession with getting the big picture. Keyword search isn't 
everything, as many long google hours have tought all of us, right? And 
I mean on-screen, I can't carry around a printout.


Does it have to be in a .lyx-file?

Would a single PDF be ok with you?

Or would it be useful if it was in HTML?

As you know, Lyx is pretty bad at handling multiple open documents, 
which contributes to my desire to have only one relevant file.


To be honest, it was three years since I wrote anything big using LyX. But 
then I didn't find it that difficult using multi-part documents. Maybe my 
expectations were low.


I read some of your links. Most of the reasons seem either outdated 
and/or developer-/maintainer-centric, as opposed to user-centric.


Well, developer-/maintainer-centric carries a *lot* of weight with me.
The most difficult part about documentation is getting it to be updated.
The second most difficult part is getting it written the first place.

Btw, these are some of the most important reasons for why I started the 
LyX wiki. I wanted to let "normal" LyX users as well as developers be able 
to contribute to the overall documentation in a more easy way.


It has not been a total failure, but the information the wiki has 
certainly not been kept as up-to-date as I'd like. One reason is probably 
the lack of editor(s).


However, I can see that maybe "customization" doesn't need to go into a 
consolidated manual. That would bring us down to a relatively minor 
reform: only merge user guide and extended features.


Maybe we could eat the cake and still have it without too much work...

What if we can come with a way that let's us keep the official 
documentation partitioned as it is, but have it automatically be merged 
into a single document for users such as yourself?


LyX isn't released that often, so even manually doing the merge once 
during each (major?) release might not be too work.


What would this require?

/Christian

--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Wiki editors (Was: please consolidate the documentation)

[christian . ridderstrom]

On Tue, 18 Jul 2006, Angus Leeming wrote:

If the editor(s) would also take up the job of maintaining the wiki, 
that would be even more valuable IMO.


The editor(s) can definitely also maintain (guide, be in charge of) the 
wiki as well. However, if editor(s) prefer I think it's quite doable to 
keep these tasks separted as well. It might also feel less intimidating to 
only be editor of one of these things...


I certainly think the wiki needs editors - just like the documentation in 
general. The editors would then be in charge of the contents and 
structure, with the support of me and any other volunteeers/developers 
helping to add content. Basically the editors are the guiding hands.


I imagine the editor(s) deciding on a structure and then asking for 
developers and users to write the parts and pieces.


Maybe what we should do is describe what the job involves and ask for 
people to volunteer? Frankly, I have no idea how this kind of position 
would be filled... do we have an election? Lottery? Anybody who wants 
becomes an editor?


As a job it only pays in terms of respect and authority, i.e. having the 
final word in how things are to be structured. And the respect part you'll 
only get if you do good work... ;-)


Btw, I'd like to thank everybody who help the wiki by removing spam as it 
appears. You are in fact partly helping as editors while doing that!


cheers
/Christian

For the record, I don't quite see myself as maintaining the wiki. In my 
mind I merely *administer* it as well as develop it.


In other words, I make sure it's operational, do software updates, try to 
document its infrastructure and develop/implement new functionality. So if 
user's come up with a request for something that they like to have working 
on the wiki, I'll try and achieve that.


There are two (big) reasons for why I am not suitable as editor for the 
wiki:


* Lack of time to both administer/support as well as be editor of the wiki

* In my opinion it's bad if the administer and editor is the same person.
  I think it is necessary to separate contents/structure from the actual
  framework/implementation. Otherwise you'll end up being to "close" to
  what you are doing, resulting in poor results and judgement.

--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Re: please consolidate the documentation

[christian . ridderstrom]

On Tue, 18 Jul 2006, Angus Leeming wrote:


No, you're right. The last editor was Mike Ressler and the last time that he
was actively involved was in the middle of 2002...


Just out curiosity, who were editors before him? (I thought I'd write it 
down here)

http://wiki.lyx.org/devel/pmwiki.php/DevelDoc/LyXEditor

/Christian

--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Re: please consolidate the documentation

[christian . ridderstrom]

On Mon, 17 Jul 2006, Steve Harris wrote:


[EMAIL PROTECTED] wrote:

Having said that, I think there at least used to be a pretty good reason 
for why the documentation was split the way it is. So I suggest you raise 
this question on the development list.


best regards
/Christian



I think the end of the splash.lyx intro screen could be
reworded a bit to devote some attention to the Wiki.


Just suggest that to the development list :-)

Actually... why not write a suggestion and just send it to the developers' 
list?



6. The LyX home page is at [http://www.lyx.org/]. Get
information about LyX, subscribe to the LyX mailing
list(s), take the LyX Graphical Tour, and more.

I think this could be changed to:

6. The LyX home page is at [http://www.lyx.org/]. Get
information about LyX, subscribe to the LyX mailing
list(s) and take the LyX Graphical Tour. Additional
documentation is available at the LyX Wiki
http://wiki.lyx.org/LyX/Manuals. [or maybe better
http://wiki.lyx.org/LyX/Documentation]


Or how about this:

6. The LyX home page is at [http://www.lyx.org/]. Get information about
   LyX, subscribe to the LyX mailing list(s), take the LyX Graphical Tour,
   and more.

7. The LyX wiki wiki is at [http://wiki.lyx.org] with additional
   documentation at [http://wiki.lyx.org/LyX/Documenation].
   Get and share tips about using LyX, read frequently asked questions
   and more.

I think documentation should point to the FAQ and the Latex Visual FAQ. 
Also a reminder to use the online archives to obtain quick answers to 
urgent problems without a hint of irritation about answering the same 
quesion over and over again. Links to archives.


The home of how to do things and solve problems.


Now I'm confused... *which* documentation should point to this? (Doesn't 
it already do that?)


Or are you talking about making a minor change to the .lyx-files making 
them point to the wiki etc? (That makes sense to me).


/Christian

--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Re: please consolidate the documentation

[christian . ridderstrom]

On Mon, 17 Jul 2006, Steve Harris wrote:

Well, I made the Wiki Entry under Manuals, but the Wiki complained the 
file was too large to accept = almost 4mb


Ok. (It might also fit under http://wiki.lyx.org/LyX/Documentation )

As for the file, could you try using YouSendIt to send it to me? (See my 
other post). I'll place it on the wiki then.


cheers
/Christian

PS. We should probably name this file with a version number corresponding 
to what LyX version it comes from.


--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Re: please consolidate the documentation

[Angus Leeming]

 <[EMAIL PROTECTED]> writes:
> Having said that, I think that what the LyX documentation mainly needs is 
> an editor - someone to guide/decide what should go into the documentation. 
> As far as I know there is no editor today (please correct me if I'm 
> wrong!)

No, you're right. The last editor was Mike Ressler and the last time that he 
was actively involved was in the middle of 2002...

I don't think the editing job is a big one. In fact, a good editor would get 
the developers to do much of his work for him ;-) Cajoling, begging and 
threatening are all important parts of the job description as, of course, is 
being able to write coherently ;-)

If the editor(s) would also take up the job of maintaining the wiki, that 
would be even more valuable IMO.

Angus

Re: please consolidate the documentation

[Sven Schreiber]

[EMAIL PROTECTED] schrieb:

> 
> As for the problem of searching all the help documentation, couldn't we
> ask the developers for a special help menu entry that says something like:
> 
> Search help documents
> 
> This seems to me like it would solve the problems you are talking about.
> Are there any other reasons for merging the documents?
> 



Yes, easily getting an overview of what's in the help file. I have this
obsession with getting the big picture. Keyword search isn't everything,
as many long google hours have tought all of us, right? And I mean
on-screen, I can't carry around a printout. As you know, Lyx is pretty
bad at handling multiple open documents, which contributes to my desire
to have only one relevant file.

I read some of your links. Most of the reasons seem either outdated
and/or developer-/maintainer-centric, as opposed to user-centric.

However, I can see that maybe "customization" doesn't need to go into a
consolidated manual. That would bring us down to a relatively minor
reform: only merge user guide and extended features.

cheers,
Sven

Re: please consolidate the documentation

[christian . ridderstrom]

On Tue, 18 Jul 2006, Martin A. Hansen wrote:

I sincerely feel that the tutorial should also be included in a single 
documentation file consisting of UG, extended etc. the reason for this 
is that you can then cross-link from the tutorial to the parts of the UG 
explaining a feature in depth. also, you can search the entire document 
for whatever and find it both in the tutorial context (with links to the 
UG context) and the UG context.


Is cross-linking and being able to search the only reason you wish to have 
these documents merged?


Please don't forget that we can ask the developers for a way to cross-link 
to *other* documents, as well as for a special mechanism that lets you 
search all the help documents.


Steven has also created a (I think) merged PDF containing all the 
information, so at least searching all of the documentation within a 
single file can be solved. (Albeit not from within LyX).


I'm not absolutely against a reduction of the number of documents, but I 
do think we should be careful. Please read the links I sent in another 
post. I definitely think there are valid reasons for keeping these 
documents separate.


We should also be careful about what the problem is that we are really 
trying to solve. If it is a matter of cross-linking, why not ask for a 
method that let's us cross-link between different documents? That is 
something that would have been useful for me when writing my (multi-part) 
thesis for instance. I'm sure it would be useful in other situations as 
well.


As for the problem of searching all the help documentation, couldn't we 
ask the developers for a special help menu entry that says something like:


Search help documents

This seems to me like it would solve the problems you are talking about. 
Are there any other reasons for merging the documents?


sincere regards
/Christian

--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Re: please consolidate the documentation

[christian . ridderstrom]

On Tue, 18 Jul 2006, Martin A. Hansen wrote:

and yes - the documentation should be a lyx document so you see for 
yourself how the lyx formatting is actually done - with the help of 
notes and cross-references.


Agreed

while the lyx documentation should contain all the relevant 
documentation to get the most out of lyx, the important wiki should IMHO 
contain everything else; such as guide showing how to complete more 
specific tasks etc. i see an evolution of documentation where a certain 
issue is discussed on the mailing list, then it is compiled as an item 
in the wiki, and if this item in due time is deemed important enough - 
it will be included in the lyx documentation. however, the documentation 
should not be overloaded! relevant is a keyword here :o)


This is how I see it as well. The problem right now is a lack of editors, 
both for organizing information in the wiki, and perhaps more importantly 
for incorporating new stuff into the LyX documents.


cheers
/Christia

--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Re: please consolidate the documentation

[christian . ridderstrom]

On Tue, 18 Jul 2006, Sven Schreiber wrote:

For people interested in helping with the documentation, please read the 
links at the bottom of this page:


http://wiki.lyx.org/LyX/Documentation#toc5

Especially look at this page

http://wiki.lyx.org/devel/pmwiki.php/Devel/MiscNotes

which containts text from a post by John Weiss, the original documentation 
editor. I'm not sure there has been a proper editor since he retired... 
Given that this has been a long while ago it is actually amazing that the 
documentation isn't more off than it is!


Please also read this *entire* thread:

http://thread.gmane.org/gmane.editors.lyx.documentation/511

and pretty please pay attention to what John says.

Having said that, I think that what the LyX documentation mainly needs is 
an editor - someone to guide/decide what should go into the documentation. 
As far as I know there is no editor today (please correct me if I'm 
wrong!)


regards
/Christian

--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Re: please consolidate the documentation

[christian . ridderstrom]

On Tue, 18 Jul 2006, Sven Schreiber wrote:


Helge Hafting schrieb:

On Mon, Jul 17, 2006 at 01:06:05PM +0200, Sven Schreiber wrote:




If you do a lot of searching, consider making a document
consisting of User's guide + extended features in one
document.  Just paste one into the other,
perhaps as part I and part II. Perhaps with Customization
as part III if you need that one too.



Ok, so I would suggest a perfect trinity: Introduction, Tutorial, 
Manual. The manual would consist of what is now the user guide, extended 
features, and customization. I guess using latex book "parts" would be 
right for that. As a normal lyx user, you would only need the manual, 
the first two docs are for beginners.


I'd just like to point out that it's previously been thought important 
that the documentation documents are normal LyX documents that don' rely 
on any special classes. In other words, it should be possible to compile 
them with a standard installation of LyX and LaTeX. FWIW, I agree with 
this.


In addition, the manuals should avoid ERT and lots of stuff in the 
preamble if I can remember correctly. Right now I can't remember the 
reason though, possibly to not scare the new reader into thinking that LyX 
documents must have this.


I take that as approval. When I have the time (not this month), I will 
try to cook something up. ( Or maybe someone else has more time in the 
short term ;-)


Note that I'm not talking about the wiki. It's nice and everything, but 
I think the first point of reference should always be the included 
documentation.


Definitely. Btw, when I first used LyX in 1997 I was really impressed with 
the documentation. Unfortunately it hasn't really been kept up to date as 
it should have since then.


cheers
/Christian

--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Re: please consolidate the documentation

[Martin A. Hansen]

nice plan sven! crisp and simple :o)

and yes - the documentation should be a lyx document so you see for yourself
how the lyx formatting is actually done - with the help of notes and
cross-references. i myself would always read the documentation in lyx and
not as pdf or dvi - i only use those to compare with the lyx document to see
the result of the formatting.

while the lyx documentation should contain all the relevant documentation to
get the most out of lyx, the important wiki should IMHO contain everything
else; such as guide showing how to complete more specific tasks etc. i see
an evolution of documentation where a certain issue is discussed on the
mailing list, then it is compiled as an item in the wiki, and if this item
in due time is deemed important enough - it will be included in the lyx
documentation. however, the documentation should not be overloaded! relevant
is a keyword here :o)



martin



On 7/18/06, Sven Schreiber <[EMAIL PROTECTED]> wrote:


Helge Hafting schrieb:
> On Mon, Jul 17, 2006 at 01:06:05PM +0200, Sven Schreiber wrote:

>
> If you do a lot of searching, consider making a document
> consisting of User's guide + extended features in one
> document.  Just paste one into the other,
> perhaps as part I and part II. Perhaps with Customization
> as part III if you need that one too.
>

Ok, so I would suggest a perfect trinity: Introduction, Tutorial,
Manual. The manual would consist of what is now the user guide, extended
features, and customization. I guess using latex book "parts" would be
right for that. As a normal lyx user, you would only need the manual,
the first two docs are for beginners.

>
> Of course, these days LyX have document branches which could be
> used to turn on/off the parts one want to see, so a single big
> document makes more sense now.  The documentation was created
> with a more limited LyX, after all.

I take that as approval. When I have the time (not this month), I will
try to cook something up. ( Or maybe someone else has more time in the
short term ;-)

Note that I'm not talking about the wiki. It's nice and everything, but
I think the first point of reference should always be the included
documentation.

Cheers,
Sven

Re: please consolidate the documentation

[Sven Schreiber]

Helge Hafting schrieb:
> On Mon, Jul 17, 2006 at 01:06:05PM +0200, Sven Schreiber wrote:

> 
> If you do a lot of searching, consider making a document
> consisting of User's guide + extended features in one
> document.  Just paste one into the other,
> perhaps as part I and part II. Perhaps with Customization
> as part III if you need that one too.
> 

Ok, so I would suggest a perfect trinity: Introduction, Tutorial,
Manual. The manual would consist of what is now the user guide, extended
features, and customization. I guess using latex book "parts" would be
right for that. As a normal lyx user, you would only need the manual,
the first two docs are for beginners.

> 
> Of course, these days LyX have document branches which could be
> used to turn on/off the parts one want to see, so a single big
> document makes more sense now.  The documentation was created
> with a more limited LyX, after all.

I take that as approval. When I have the time (not this month), I will
try to cook something up. ( Or maybe someone else has more time in the
short term ;-)

Note that I'm not talking about the wiki. It's nice and everything, but
I think the first point of reference should always be the included
documentation.

Cheers,
Sven

Re: please consolidate the documentation

[Martin A. Hansen]

I sincerely feel that the tutorial should also be included in a single
documentation file consisting of UG, extended etc. the reason for this is
that you can then cross-link from the tutorial to the parts of the UG
explaining a feature in depth. also, you can search the entire document for
whatever and find it both in the tutorial context (with links to the UG
context) and the UG context.

Finally, I dont see why the tutorial should _not_ be included.


Martin



On 7/18/06, Steve Harris <[EMAIL PROTECTED]> wrote:


[EMAIL PROTECTED] wrote:

> Having said that, I think there at least used to be a pretty good reason
> for why the documentation was split the way it is. So I suggest you
> raise this question on the development list.
>
> best regards
> /Christian
>

I think the end of the splash.lyx intro screen could be
reworded a bit to devote some attention to the Wiki.

6. The LyX home page is at [http://www.lyx.org/]. Get
information about LyX, subscribe to the LyX mailing
list(s), take the LyX Graphical Tour, and more.

I think this could be changed to:

6. The LyX home page is at [http://www.lyx.org/]. Get
information about LyX, subscribe to the LyX mailing
list(s) and take the LyX Graphical Tour. Additional
documentation is available at the LyX Wiki
http://wiki.lyx.org/LyX/Manuals. [or maybe better
http://wiki.lyx.org/LyX/Documentation]

I think documentation should point to the FAQ and
the Latex Visual FAQ. Also a reminder to use the
online archives to obtain quick answers to urgent
problems without a hint of irritation about answering
the same quesion over and over again. Links to archives.

The home of how to do things and solve problems.
Unfortunately I won't be able to contribute to the
documentation project as I like to explain myself
fully and in detail. The puny Wiki can't accomodate
the size of my masterpieces. Just kidding :-)

The developers would have to approve a change of
copy to the splash.lyx intro. Consolidation of the
help documents could be offered in another format
in another location while advertising the Wiki.

Perspicuity and Perspicacity, how sublimely pragmatic,
Stephen :-)the oxymoron, how's that for credentials?!

Ps, A little extra juice for the Wiki, hip, hip,

Re: please consolidate the documentation

[Steve Harris]

[EMAIL PROTECTED] wrote:

Having said that, I think there at least used to be a pretty good reason 
for why the documentation was split the way it is. So I suggest you 
raise this question on the development list.


best regards
/Christian



I think the end of the splash.lyx intro screen could be
reworded a bit to devote some attention to the Wiki.

6. The LyX home page is at [http://www.lyx.org/]. Get
information about LyX, subscribe to the LyX mailing
list(s), take the LyX Graphical Tour, and more.

I think this could be changed to:

6. The LyX home page is at [http://www.lyx.org/]. Get
information about LyX, subscribe to the LyX mailing
list(s) and take the LyX Graphical Tour. Additional
documentation is available at the LyX Wiki
http://wiki.lyx.org/LyX/Manuals. [or maybe better
http://wiki.lyx.org/LyX/Documentation]

I think documentation should point to the FAQ and
the Latex Visual FAQ. Also a reminder to use the
online archives to obtain quick answers to urgent
problems without a hint of irritation about answering
the same quesion over and over again. Links to archives.

The home of how to do things and solve problems.
Unfortunately I won't be able to contribute to the
documentation project as I like to explain myself
fully and in detail. The puny Wiki can't accomodate
the size of my masterpieces. Just kidding :-)

The developers would have to approve a change of
copy to the splash.lyx intro. Consolidation of the
help documents could be offered in another format
in another location while advertising the Wiki.

Perspicuity and Perspicacity, how sublimely pragmatic,
Stephen :-)the oxymoron, how's that for credentials?!

Ps, A little extra juice for the Wiki, hip, hip,

Re: please consolidate the documentation

[Steve Harris]

Ed Gatzke wrote:

Change the "titles" to "Parts" and copy paste the rest in.

   Use Insert->Insert File->LyX file.

Rich



I think you miss out on some formatting, and you may have trouble with multiple
titles/authors and different preambles.  


To make one super document, the title of the individual files should be a 
"Part".

I just tried the insert method to combine a couple of files (tutorial and user
guide) and nothing came out due to a preamble problem.

You probably could pull some latex magick with if and include, but it would not
be very clean in lyx.







Well, I made the Wiki Entry under Manuals, but the Wiki
complained the file was too large to accept = almost 4mb

So I sent the 4 files seperately hoping that Chris can
make new pdf -> combine multiple files,
put them into the right order and OK.
The binder file should be renamed LyXGuides.pdf
Then the separate files can be deleted.
It would have been easier to upload the finished file.

I wrote a description already.
http://wiki.lyx.org/LyX/Manuals
* Searchable Contents of Tutorial, UG, Ext., & Customization Guides PDF 
file


Regards,
Stephen

Re: please consolidate the documentation

[Steve Harris]

Ed Gatzke wrote:

Change the "titles" to "Parts" and copy paste the rest in.

   Use Insert->Insert File->LyX file.

Rich



I think you miss out on some formatting, and you may have trouble with multiple
titles/authors and different preambles.  


To make one super document, the title of the individual files should be a 
"Part".

I just tried the insert method to combine a couple of files (tutorial and user
guide) and nothing came out due to a preamble problem.

You probably could pull some latex magick with if and include, but it would not
be very clean in lyx.







PC World comes up with a lot of tips. I used Paul Smith's
suggested method of joining them in one large yearly file
which I burned to a cd (with other stuff) and take to jobs.

I'll do this with the UG, Extended, and Customization.
I think a one or two line link/description of the LyX Wiki,
with mention of a searchable "Inclusive User Manual" (FAQ)
would suffice at the bottom of the splash.lyx which
shows up after an installation. I have grown tired of the
humor in the footnote. I'll just go ahead and do it and
you guys can see if its good enough. I will give it a
clever distinctive title like: "Little Known Enchantments
of the LyX Wizards" :-) Maybe that title won't pass the
newly incarnated guardian of the LyX Wiki Stygian portal.

I'll send another post when it is up with the location.

Regards,
Stephen

Re: please consolidate the documentation

[Ed Gatzke]

> > Change the "titles" to "Parts" and copy paste the rest in.
> 
>Use Insert->Insert File->LyX file.
> 
> Rich


I think you miss out on some formatting, and you may have trouble with multiple
titles/authors and different preambles.  

To make one super document, the title of the individual files should be a 
"Part".

I just tried the insert method to combine a couple of files (tutorial and user
guide) and nothing came out due to a preamble problem.

You probably could pull some latex magick with if and include, but it would not
be very clean in lyx.

Re: please consolidate the documentation

[Helge Hafting]

On Mon, Jul 17, 2006 at 01:06:05PM +0200, Sven Schreiber wrote:
> Dear lyxers,
> 
> don't know if this is the right list, but anyway: I have tried many
> times to understand the logic behind the various help documents
> (tutorial, user guide, extended features, ... and this list goes

The logic is simple - different documents for different purposes:
Introduction: Short introduction about what LyX is for.
  You get this one the first time you run LyX.
  It also have a list of all the help documents
  and what they are for.

Tutorial: A tutorial that will get you started using LyX.
  Such as writing your first document, printing it,
  simple editing. This is for beginners.

User's Guide: How to do everything that is supported in LyX.
  This is where you go for the details.  This is
  where you search for stuff. 
  
Extended features: A continuation of the user's guide, with
  specialist stuff like latex commands, indexes,
  more document classes and more.

Customization: How to customize LyX, such as adding your
 own document class, translating LyX itself
 into another language and more.

  
If you do a lot of searching, consider making a document
consisting of User's guide + extended features in one
document.  Just paste one into the other,
perhaps as part I and part II. Perhaps with Customization
as part III if you need that one too.



> on), but now I've had enough -- did you know that branches are
> explained not in extended features, no no no, but in the user's guide
> under "more tools"? Note the subtle difference between "extended" and
> "more", "features" and "tools". This is crazy!
> 
Perhaps User's guide and extended features should be merged.  I think
the other documents have sufficiently different purposes to justify
being separate.  You don't want to hand someone a big document 
consisting of all five just to tell them what LyX is - that's what
the "Introduction" is for. . .

> I dare to claim that much of the traffic on this list exists because
> many times somebody wants to RTFM, but -- which one? And not having
> found the answer in the first (of the many) documents, she or he resorts
> to the mailing list, where enough kind and helpful people know all the
> documentation by heart. That's great, but it's also inefficient.
> 
Well, five documents isn't that much, and usually it is in the User's
guide.  :-)  Making a concatenated document for searching shouldn't
be hard though.



> So please consolidate the documentation into one file (or let me do it).
> 
> I had to let off some steam, thou shalt not feel offended...
>
Nothing wrong with making a single document, but there are'
times when one don't want everything.  Someone who want to
print the user's guide for reference might not want to spend
paper and ink "Customization" for example - few people get into this
part.

Of course, these days LyX have document branches which could be
used to turn on/off the parts one want to see, so a single big
document makes more sense now.  The documentation was created
with a more limited LyX, after all.

Helge Hafting

Re: please consolidate the documentation

[christian . ridderstrom]

On Mon, 17 Jul 2006, Daniel Watkins wrote:

I think there is one. At least they have a mailing list. Try sending a 
mail to their mailing list at 
lyx-docs@lists.lyx.org


That has nothing but automatically sent 'Wiki changes' updates. I 
unsubscribed a while ago, so it may ahve changed since.


The list 'lyx-docs' is the documentation list, but it is very slow 
(unfortunately). If one or more of you are serious about improving the 
documentation I am sure it will be *extremely* welcome!


Your best bet would probably be to ask on the development list, as any 
documenteers will almost certainly read that. And even if they don't, 
the developers should be able to point you in the right direction.


Yes, it is probably best to bring this up on the development list. Send an 
email here:


lyx-devel@lists.lyx.org

Someone mentioned a documentation team, but unfortunately that team 
basically that the team has no members these days...


Having said that, I think there at least used to be a pretty good reason 
for why the documentation was split the way it is. So I suggest you raise 
this question on the development list.


best regards
/Christian

PS. I'm sort of involved with the documentation as I administer the wiki.

Which reminds me... the FAQ on the wiki could sure use some help. 
Classifying the questions for instance, instead of having them in two 
unsorted pages. I'll look it tomorrow and comeback with plan in case there 
are people on this list that would like to help!


--
Christian Ridderström, +46-8-768 39 44   http://www.md.kth.se/~chr

Re: please consolidate the documentation

[Rich Shepard]

On Mon, 17 Jul 2006, Ed Gatzke wrote:


Change the "titles" to "Parts" and copy paste the rest in.


  Use Insert->Insert File->LyX file.

Rich

--
Richard B. Shepard, Ph.D.   |The Environmental Permitting
Applied Ecosystem Services, Inc.(TM)|Accelerator
 Voice: 503-667-4517  Fax: 503-667-8863

Re: please consolidate the documentation

[Ed Gatzke]

 
> agreed!
> 
> one file would be so nice, because then you could search for a particular
> keyword you are looking for without having to open all the different help
> files. and since lyx/latex is so good at sectioning, it would be straight
> forward to combine them all.
> 

It does not take much to convert the documentation to one lyx file.

Change the "titles" to "Parts" and copy paste the rest in.  With some minor mods
you should be good to go.  

Not to bad, easy to do.  Gotta copy preambles too... Here you go!

http://www.cse.sc.edu/~gatzke/overall.lyx
http://www.cse.sc.edu/~gatzke/overall.pdf


Ed

Re: please consolidate the documentation

[Daniel Watkins]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

Andreas K. wrote:
> I think there is one. At least they have a mailing list. Try sending a
> mail to their mailing list at
> lyx-docs@lists.lyx.org

That has nothing but automatically sent 'Wiki changes' updates. I
unsubscribed a while ago, so it may ahve changed since.

Your best bet would probably be to ask on the development list, as any
documenteers will almost certainly read that. And even if they don't, the
developers should be able to point you in the right direction.

Dan
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.4 (GNU/Linux)

iD8DBQFEu+iulFI7BNKVCIkRArRZAJ4yM2uOyogqkneorNf2h6MZL7JotwCdEHiH
m+fKf9QBGD/0ruhB977MkAk=
=47CT
-END PGP SIGNATURE-

Re: please consolidate the documentation

[Andreas K .]

Sven Schreiber <[EMAIL PROTECTED]> writes:

> Well isn't there a documentation team? 

I think there is one. At least they have a mailing list. Try sending a mail to 
their mailing list at lyx-docs@lists.lyx.org

Andreas

Re: please consolidate the documentation

[Daniel Watkins]

Sven Schreiber wrote:
> Well isn't there a documentation team?
AFAIK, you just became it.

> What would be the recommended way of making a concrete proposal, attach
> the resulting single lyx file to a message on this list? 
As this would be around 1.5MB (assuming that you just stuck all of the
documentation together), that might be a little too much. If you have some
webspace, you could put it in there. Failing that, there're a number of
free upload site you could try, such as Bigupload
(http://www.bigupload.com) or YouSendIt (http://www.yousendit.com).

Dan

Re: please consolidate the documentation

[Sven Schreiber]

Daniel Watkins schrieb:
> Sven Schreiber wrote:
>>> So please consolidate the documentation into one file (or let me do it).
> 
> I promise you, no-one here is going to hold you back, if you're
> volunteering[*]. :p
> 

Well isn't there a documentation team? Maybe they don't think it's a
good idea? What would be the recommended way of making a concrete
proposal, attach the resulting single lyx file to a message on this list?

-sven

Re: please consolidate the documentation

[Paul Smith]

On 7/17/06, Martin A. Hansen <[EMAIL PROTECTED]> wrote:

agreed!

one file would be so nice, because then you could search for a particular
keyword you are looking for without having to open all the different help
files. and since lyx/latex is so good at sectioning, it would be straight
forward to combine them all.


As a temporary solution, produce a pdf output for each help file and,
then, by using pdftk (or another tool) join all of them in a single
pdf file. Afterwards, you can search the joint pdf file with the
search tool of Acrobat Reader, for instance.

Paul

Re: please consolidate the documentation

[Daniel Watkins]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

Sven Schreiber wrote:
> So please consolidate the documentation into one file (or let me do it).

I promise you, no-one here is going to hold you back, if you're
volunteering[*]. :p

Dan



[Footnote *: Unless, of course, you submit multi-change patches, then all
hell breaks loose. ;)]
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.4 (GNU/Linux)

iD8DBQFEu3LylFI7BNKVCIkRAnHsAJ9sI2k23qrGsFfn5DEkMUaYNbk22ACfZE6g
Afb1TV2X0oiI3WvixKfYMd8=
=8NKi
-END PGP SIGNATURE-

Re: please consolidate the documentation

[Martin A. Hansen]

agreed!

one file would be so nice, because then you could search for a particular
keyword you are looking for without having to open all the different help
files. and since lyx/latex is so good at sectioning, it would be straight
forward to combine them all.


martin


On 7/17/06, Sven Schreiber <[EMAIL PROTECTED]> wrote:


Dear lyxers,

don't know if this is the right list, but anyway: I have tried many
times to understand the logic behind the various help documents
(tutorial, user guide, extended features, ... and this list goes
on), but now I've had enough -- did you know that branches are
explained not in extended features, no no no, but in the user's guide
under "more tools"? Note the subtle difference between "extended" and
"more", "features" and "tools". This is crazy!

I dare to claim that much of the traffic on this list exists because
many times somebody wants to RTFM, but -- which one? And not having
found the answer in the first (of the many) documents, she or he resorts
to the mailing list, where enough kind and helpful people know all the
documentation by heart. That's great, but it's also inefficient.

So please consolidate the documentation into one file (or let me do it).

I had to let off some steam, thou shalt not feel offended...

cheers,
Sven

please consolidate the documentation

[Sven Schreiber]

Dear lyxers,

don't know if this is the right list, but anyway: I have tried many
times to understand the logic behind the various help documents
(tutorial, user guide, extended features, ... and this list goes
on), but now I've had enough -- did you know that branches are
explained not in extended features, no no no, but in the user's guide
under "more tools"? Note the subtle difference between "extended" and
"more", "features" and "tools". This is crazy!

I dare to claim that much of the traffic on this list exists because
many times somebody wants to RTFM, but -- which one? And not having
found the answer in the first (of the many) documents, she or he resorts
to the mailing list, where enough kind and helpful people know all the
documentation by heart. That's great, but it's also inefficient.

So please consolidate the documentation into one file (or let me do it).

I had to let off some steam, thou shalt not feel offended...

cheers,
Sven