gmane.editors.lyx.devel

Uwe Stöhr | 6 Oct 20:50

changeset/26771- about the documentation files

> Uwe, I've used change tracking here, too. If you don't want or need to check this, let me know,
 > of just accept all changes and commit it.

I currently only maintain the following documentation files:
- UserGuide
- Math
- EmbeddedObjects
- Intro
- Tutorial

So when changing them it would be nice to use change tracking. I can then also take the changes to
the other languages. Currently we have active documentation members for Spanish, French, German, and
partly Italian.

The other documentation files are in many parts outdated, but I haven't found the time to update the
Customization and Extended manual until now. I saw that you in the meantime updated the
Customization manual - good job!
Pavel takes care about the LFUNS manual, we all of the LaTeX Config file. Thanks to InsetInfo,
Shortcuts is automatically updated. SCons and I guess also CMake creates the Table of Contents files
automatically.

Concerning the FAQ.lyx manual, I would like to drop it as most of its content is in our other
manuals and the FAQ section of the Wiki. The Wiki also has the advantage that everybody can help to
keep it up to date. So instead up adding things to the FAQ.lyx file, we better add this to our Wiki.
Opinions if I can drop the English FAQ.lyx file? (Our Wiki does not yet support other languages than
English.)

regards Uwe

(Continue reading)

Pavel Sanda | 6 Oct 22:20

Re: changeset/26771- about the documentation files

Uwe Stöhr wrote:
>> Uwe, I've used change tracking here, too. If you don't want or need to 
>> check this, let me know,
> > of just accept all changes and commit it.
>
> Concerning the FAQ.lyx manual, I would like to drop it as most of its 

+1

more on the help menu - imho it would be helpful if we could join some
manuals together - for example there is no reason to have embedded objects manual
to have separated. i also wonder whats the reason for extended manual to be separated.

next probably problematic draft would be to get rid of the table of contents file.
i can't remember i have ever touched it, and because one can't click in hypertext
way in its sections, i wonder how is this file to be used actually. its generation
takes a lot of time when make install is being done. last but not least i hope
for complete 'LyX Book' to be released synchronously with 1.6, which will contain
all manuals put together, with working pdf bookmarks, so the the contents will
be accessible in a more feasible way.

pavel

rgheck | 6 Oct 23:06

Re: changeset/26771- about the documentation files

Pavel Sanda wrote:
> Uwe Stöhr wrote:
>   
>>> Uwe, I've used change tracking here, too. If you don't want or need to 
>>> check this, let me know,
>>> of just accept all changes and commit it.
>>>       
>> Concerning the FAQ.lyx manual, I would like to drop it as most of its 
>>     
>
> +1
>
> more on the help menu - imho it would be helpful if we could join some
> manuals together - for example there is no reason to have embedded objects manual
> to have separated. i also wonder whats the reason for extended manual to be separated.
>
>   
This is actually stated in the first paragraph of so of that manual.  
And much of it really is quite advanced and not really of interest to 
the average user. So maybe it should really be called the "Advanced 
Features" manual, or something of the sort.

I'm going to have a look at that one. Some of it is very out of date. 
(But not the version control stuff!). I'm guessing that, in fact, 
there's a lot of stuff in that manual that should really just be 
removed. Or perhaps moved to some other file or files.

> next probably problematic draft would be to get rid of the table of contents file.
> i can't remember i have ever touched it, and because one can't click in hypertext
> way in its sections, i wonder how is this file to be used actually. its generation

(Continue reading)

Pavel Sanda | 6 Oct 23:18

Re: changeset/26771- about the documentation files

Richard Heck wrote:
> I'm going to have a look at that one. Some of it is very out of date. (But 

have seen there are ~10 [[FIXME]] items in layout-tags section in Customization
manual. since you have worked on layouts/modules stuff a lot, maybe you are able
to describe these tags?

>> last but not least i hope
>> for complete 'LyX Book' to be released synchronously with 1.6, which will 
>> contain
>> all manuals put together, with working pdf bookmarks, so the the contents 
>> will
>> be accessible in a more feasible way.
>>
>>   
> That'd be nice....

i asked Uwe for this, and if he won't find time i'll do some not-so-nice version
myself, since i need search through all our docs quite often...

pavel

rgheck | 6 Oct 22:50

Re: changeset/26771- about the documentation files

Uwe Stöhr wrote:
> I currently only maintain the following documentation files:
> - UserGuide
> - Math
> - EmbeddedObjects
> - Intro
> - Tutorial
>
> So when changing them it would be nice to use change tracking. I can 
> then also take the changes to the other languages. Currently we have 
> active documentation members for Spanish, French, German, and partly 
> Italian.
>
> The other documentation files are in many parts outdated, but I 
> haven't found the time to update the Customization and Extended manual 
> until now. I saw that you in the meantime updated the Customization 
> manual - good job!
>
Thanks. Most of the Customization manual should now be up to date. The 
part that isn't, or at least may not be, is section 6, "Including 
External Material". I looked over it briefly, but I have never used, and 
do not understand, that stuff. So it's totally unclear to me whether it 
is right or wrong. I'll add a comment to that effect. If there's anyone 
who does understand it, perhaps they could have a look.

I'll have a look at the Extended manual.

> Concerning the FAQ.lyx manual, I would like to drop it as most of its 
> content is in our other manuals and the FAQ section of the Wiki. The 
> Wiki also has the advantage that everybody can help to keep it up to

(Continue reading)

Uwe Stöhr | 7 Oct 03:18

Re: changeset/26771- about the documentation files

rgheck schrieb:

> Thanks. Most of the Customization manual should now be up to date. The 
> part that isn't, or at least may not be, is section 6, "Including 
> External Material".

This can be removed as this is already included in the EmbeddedObjects manual. I'll have a look at 
this the next days.

> I'd drop them all. If the other ones are as out of date as the English 
> one is, it might do more harm than good.

They are even more outdated.

> Maybe a better thing would be 
> an FAQ that simply consisted of cross-references to places in the 
> various manuals where questions are answered.

Maybe this could be a solution.
What do others say about this?

regards Uwe

Jean-Marc Lasgouttes | 7 Oct 07:31

Re: changeset/26771- about the documentation files

>> Maybe a better thing would be an FAQ that simply consisted of  
>> cross-references to places in the various manuals where questions  
>> are answered.
>
> Maybe this could be a solution.
> What do others say about this?

It would make sense if we had support for inter-docs references.  
Otherwise I fear it will be awkward to use.
We could also have a per-document FAQ at the beginning of each document.

JMarc

rgheck | 7 Oct 16:21

Re: changeset/26771- about the documentation files

Jean-Marc Lasgouttes wrote:
>>> Maybe a better thing would be an FAQ that simply consisted of 
>>> cross-references to places in the various manuals where questions 
>>> are answered.
>>
>> Maybe this could be a solution.
>> What do others say about this?
>
> It would make sense if we had support for inter-docs references. 
> Otherwise I fear it will be awkward to use.
> We could also have a per-document FAQ at the beginning of each document.
>
That would work for now, and they could be unified later.

rh

rgheck | 7 Oct 16:24

Re: changeset/26771- about the documentation files

Uwe Stöhr wrote:
> rgheck schrieb:
>
>> Thanks. Most of the Customization manual should now be up to date. 
>> The part that isn't, or at least may not be, is section 6, "Including 
>> External Material".
>
> This can be removed as this is already included in the EmbeddedObjects 
> manual. I'll have a look at this the next days.
>
I think the material in Customization is different. It explains how to 
define new templates, etc, whereas Embedded Objects just talks about the 
ones we have.

>> I'd drop them all. If the other ones are as out of date as the 
>> English one is, it might do more harm than good.
>
> They are even more outdated.
>
In that case, we should definitely drop them, even if we don't have any 
other plan.

rh

Christian Ridderström | 7 Oct 22:24

Re: changeset/26771- about the documentation files

On Tue, 7 Oct 2008, rgheck wrote:

> Uwe Stöhr wrote:
>>  rgheck schrieb:
>> 
>> >  Thanks. Most of the Customization manual should now be up to date. The 
>> >  part that isn't, or at least may not be, is section 6, "Including 
>> >  External Material".
>>
>>  This can be removed as this is already included in the EmbeddedObjects
>>  manual. I'll have a look at this the next days.
>> 
> I think the material in Customization is different. It explains how to define 
> new templates, etc, whereas Embedded Objects just talks about the ones we 
> have.
>
>> >  I'd drop them all. If the other ones are as out of date as the English 
>> >  one is, it might do more harm than good.
>>
>>  They are even more outdated.

> In that case, we should definitely drop them, even if we don't have any 
> other plan.

I'm in favour of dropping the FAQ:s.lyx. However, this will implicitly 
place a depency:
* The wiki server is running
* The user has internet access

Both of these can of course be mitigated by generating an FAQ document

(Continue reading)

Uwe Stöhr | 7 Oct 19:14

Re: changeset/26771- about the documentation files

 > more on the help menu - imho it would be helpful if we could join some
 > manuals together

Why would this be an advantage?

 >- for example there is no reason to have embedded objects
 > manual to have separated. i also wonder whats the reason for extended manual to be
 > separated.

Because they are not of interest for average users. They are designed to explain the things that are 
mentioned in the UserGuide in detail including needed TeX code commands for specials formats. Every 
manual is designed to be its own (ready to print) book, includinng a TOC, index, bibliography.

Concatenate them wouldn't be an advantage, you then only get a 350 page beast that is not 
maintainable and also not usefule to find the infos you are searching for as you then have e.g. 2-3 
different places describing something about graphics.

 > next probably problematic draft would be to get rid of the table of contents
 > file.
 > i can't remember i have ever touched it, and because one can't click in
 > hypertext way in its sections, i wonder how is this file to be used actually. its
 > generation takes a lot of time when make install is being done.

We can indeed get rid of them.

 >  last but not least i hope
 > for complete 'LyX Book' to be released synchronously with 1.6, which will
 > contain
 > all manuals put together, with working pdf bookmarks, so the the contents will
 > be accessible in a more feasible way.

(Continue reading)

Pavel Sanda | 7 Oct 22:20

Re: changeset/26771- about the documentation files

Uwe Stöhr wrote:
> > more on the help menu - imho it would be helpful if we could join some
> > manuals together
>
> Why would this be an advantage?

because i can use single search for one document instead of guessing what to
open.

pavel

Guenter Milde | 8 Oct 11:25

Re: changeset/26771- about the documentation files

Uwe Stöhr <uwestoehr@...> schrieb:

> >- for example there is no reason to have embedded objects manual to
> >  have separated. i also wonder whats the reason for extended manual
> >  to be separated.

> Because they are not of interest for average users. They are designed
> to explain the things that are mentioned in the UserGuide in detail
> including needed TeX code commands for specials formats. 

Even with the current splitting, opening a help document in LyX is a
lengthy process. 

OTOH, navigating (especially following cross references) between
different LyX documents is not as easy as navigating inside one document.

> Every manual is designed to be its own (ready to print) book, including
> a TOC, index, bibliography.

Why not create a master document (LyXGuide.lyx, say) which includes all
the guides as Chapters or Parts.  Placing the individual TOC, ...
commands in a "standalone" branch (which is disabled in the master but
enabled in the separate Guides) will retain the "Every manual is ... its
own ... book" feature.

> Concatenate them wouldn't be an advantage, you then only get a 350 page
> beast that is not maintainable and also not usefule to find the infos
> you are searching for as you then have e.g. 2-3 different places
> describing something about graphics.

(Continue reading)

Christian Ridderström | 7 Oct 22:26

Re: changeset/26771- about the documentation files

On Mon, 6 Oct 2008, Uwe Stöhr wrote:

> s and the FAQ section of the Wiki. The Wiki also has the advantage that 
> everybody can help to keep it up to date. So instead up adding things to 
> the FAQ.lyx file, we better add this to our Wiki. Opinions if I can drop 
> the English FAQ.lyx file? (Our Wiki does not yet support other languages 
> than English.)

What kind of "support" would you like? (It's a serious question).

Btw, the FAQ-pages on the wiki need a _serious_ restructuring. They also 
lack proper version control, so when looking at a specific question, 
there's no way of knowing the LyX version to which it pertains.

regards
/Christian

--

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

Uwe Stöhr | 8 Oct 00:47

Re: changeset/26771- about the documentation files

 > What kind of "support" would you like? (It's a serious question).

We have FAQ.lyx files for different languages. Dropping e.g. the Russian version would be a 
dataloss. So we have to set up the Wiki so that you can use different languages. Just the same way 
the Wikipedia does it:
- the English address is "wiki.lyx.org", the Russian "ru.wiki.lyx.org"
- When there are Wiki pages with the same content you have a hyperlink on the left page side to jump 
to the different language versions

But before we can do this, we need a Russian to set up the Russian main Wiki page. Other wise you 
still have to go the the English Wiki and then by the hyperlink to the Russian version. But this is 
only possible when you already know English. So we have to find a way to provide the Infos of the 
Russian FAQ.lyx to our Wiki so that Russian users can access them without to know English. I guess 
that this is currently not possible.

regards Uwe

Pavel Sanda | 8 Oct 01:09

Re: changeset/26771- about the documentation files

Uwe Stöhr wrote:
> > What kind of "support" would you like? (It's a serious question).
>
> We have FAQ.lyx files for different languages. Dropping e.g. the Russian 
> version would be a dataloss. So we have to set up the Wiki so that you can 
> use different languages. Just the same way the Wikipedia does it:
> - the English address is "wiki.lyx.org", the Russian "ru.wiki.lyx.org"
> - When there are Wiki pages with the same content you have a hyperlink on 
> the left page side to jump to the different language versions
>
> But before we can do this, we need a Russian to set up the Russian main 
> Wiki page.

this is megalomanic.
pavel

Joost Verburg | 8 Oct 14:44

Re: changeset/26771- about the documentation files

Uwe Stöhr wrote:
> But before we can do this, we need a Russian to set up the Russian main 
> Wiki page. Other wise you still have to go the the English Wiki and then 
> by the hyperlink to the Russian version. But this is only possible when 
> you already know English. So we have to find a way to provide the Infos 
> of the Russian FAQ.lyx to our Wiki so that Russian users can access them 
> without to know English. I guess that this is currently not possible.

I would keep this limited to a maybe a single FAQ page in different 
languages, not a complete wiki.

Joost

Return

Return to gmane.editors.lyx.devel.

Advertisement

Search Archive

Language

Change language

Options

Current view: Threads only / Showing only 20 lines / Not hiding cited text.
Change to All messages, whole messages, or hide cited text.

Post a message
NNTP Newsgroup
Classic Gmane web interface
XML

XML

RSS Feed
List Information

About Gmane