Re: [rework docs] reasons, plans, questions
On Thu, Jan 13, 2005 at 03:34:24AM +0100, Uwe Sthr wrote: ...because manuals should be as dry as dust, and so boring that nobody looks at them? Yes of course ;-) I mean commands like If you use Export-PostScript you can start drinking a coffee (translated from the german docs). If users don't laugh about it, it scares them off. Running latex on a book takes time. There's no need trying to hide that fact in the docs. Fortunately, this is something people don't have to do all the time, so you can calm them down with that, if you worry. And of course they won't wait long for a postscript conversion on a two-page text... Nobody read a UserGuide from the beginning to the end. Maybe I'm special then. When I get something, I try reading the manuals _first_. Of course I sort of give that up if they're bad, but the lyx manual was fine. Well written and showing all the stuff one can do. I tried out various interesting things with test documents. Of course a manual for a editing tool is somewhat special, in that you actually read the manual with the tool itself. Still, it was a nice experience. Don't underestimate people's curiosity, the lyx manual isn't boring for someone interested in editing, typesetting, poptions and tricks. Except of the tutorial, docs are used as reference book. Helge Hafting
Re: [rework docs] reasons, plans, questions
On Thu, Jan 13, 2005 at 03:34:24AM +0100, Uwe StÃhr wrote: > >...because manuals should be as dry as dust, and so boring that nobody > >looks at them? > > Yes of course ;-) I mean commands like "If you use Export->PostScript > you can start drinking a coffee" (translated from the german docs). If > users don't laugh about it, it scares them off. Running latex on a book takes time. There's no need trying to hide that fact in the docs. Fortunately, this is something people don't have to do all the time, so you can calm them down with that, if you worry. And of course they won't wait long for a postscript conversion on a two-page text... > Nobody read a UserGuide from the beginning to the end. Maybe I'm special then. When I get something, I try reading the manuals _first_. Of course I sort of give that up if they're bad, but the lyx manual was fine. Well written and showing all the stuff one can do. I tried out various interesting things with test documents. Of course a manual for a editing tool is somewhat special, in that you actually read the manual with the tool itself. Still, it was a nice experience. Don't underestimate peopleï's curiosity, the lyx manual isnï't boring for someone interested in editing, typesetting, poptions and tricks. > Except of the > tutorial, docs are used as reference book. > Helge Hafting
Re: [rework docs] reasons, plans, questions
John Weiss wrote: A master document including the parts is a good idea; maybe the individual parts can still be rewritten some so they don't repeat to much. The repetition was added, intentionally, after I was told that I had the wrong balance. Change the individual docs to reduce the repetition, and you'll soon be hearing shrieks of pain from LyX users. This is, yet again, one of those compromises we made between read online and read printed version. Now that the flames are dying down a bit, maybe I can throw in my two cents hear 'em clink. I agree with John, repetition shouldn't be a problem. The traditional drawback to repeating information in two different places is that it can get out of sync when a writer makes changes in one place and doesn't know about (or forgets) the other. The question is, would using input files (Insert menu - Include file...) cause more problems (extra snippet files lying around, the hassle of opening them to see what's inside) than it solves? -- Larry Kollark o l l a r @ a l l t e l . n e t The hardest part of all this is the part that requires thinking. -- Paul Tyson, on xml-doc
Re: [rework docs] reasons, plans, questions
John Weiss wrote: A master document including the parts is a good idea; maybe the individual parts can still be rewritten some so they don't repeat to much. The repetition was added, intentionally, after I was told that I had the wrong balance. Change the individual docs to reduce the repetition, and you'll soon be hearing shrieks of pain from LyX users. This is, yet again, one of those compromises we made between "read online" and "read printed version". Now that the flames are dying down a bit, maybe I can throw in my two cents & hear 'em clink. I agree with John, repetition shouldn't be a problem. The traditional drawback to repeating information in two different places is that it can get out of sync when a writer makes changes in one place and doesn't know about (or forgets) the other. The question is, would using input files (Insert menu -> Include file...) cause more problems (extra "snippet" files lying around, the hassle of opening them to see what's inside) than it solves? -- Larry Kollark o l l a r @ a l l t e l . n e t "The hardest part of all this is the part that requires thinking." -- Paul Tyson, on xml-doc
Re: [rework docs] reasons, plans, questions
On Thu, Jan 13, 2005 at 10:07:27AM +0100, Jean-Marc Lasgouttes wrote: Uwe == Uwe Stöhr [EMAIL PROTECTED] writes: Uwe John Weiss wrote: Doesn't follow a strucutred concept, eh? Maybe you should read the mailling list archives before insulting me. Uwe Sorry I wouldn't harm anybody. I didn't know that there is an Uwe active doc maintainer. I asked that on the docs- list a year ago Uwe and nobody replied. Are you the current doc maintainer? You are right that there is no active documentation maintainer, and it has been so for several years. John takes offense at the fact that you described his cherished baby as 'not structured'... No, more that he's saying no structure exists, when historical evidence (and my own memory of all that work!) points to the contrary. So the conclusion is that your activity on the docs is much needed and very appreciated, but you should not criticize John's work, at least in public ;) Not at all! If my original design plan for the docs has drifted too far from present needs, then by all means, Refactor Away! Which is exactly what we do with the code itself. Just be sure not to repeat the Mistakes of the Past as you change things. *That* drives me nutz. g ;) -- John Weiss
Re: [rework docs] reasons, plans, questions
On Thu, Jan 13, 2005 at 03:34:24AM +0100, Uwe Stöhr wrote: John Weiss wrote: Doesn't follow a structured concept, eh? Maybe you should read the mailling list archives before insulting me. Sorry I wouldn't harm anybody. I didn't know that there is an active doc maintainer. I asked that on the docs- list a year ago and nobody replied. Are you the current doc maintainer? Sure, go ahead and be snide. I suppose I deserve it... No, Uwe, there's no one actively maintaining the docs. There hasn't been for a few years now. But that could be for two reasons: (1) I and my helpers did our jobs right 7 years ago and came up with something which, while scratched and dinged up in places, is still servicable. Or (2) I didn't do my job right and the docs are so bad-off as to be useless, yet the User community is afraid to take on the daunting task of writing new ones. I don't subscribe to the LyX user's list (too much traffic, and I have enough trouble keeping up with the devel docs lists these days), so I'm not hearing the howls of pain caused by the existing docs that you seem to be. I missed a structured concept in that way, that I often have to search in all three parts, the UserGuide, Customization and Extended for keywords to find the information. For a normal user it is often not clear what is extended or what might be in the UserGuide. - Partly, this is semantics. You should've seen the Great Naming Debate that went on for User Guide and Extended. bleh Boils down, again, to having an international user base who put slightly different connotations on English words depending on what they translate them to in their heads. You are not now, nor ever will fix that, Uwe. - Partly, its changes introduced to the Introduction.lyx manual. (I don't remember it being as long as what I see right now, just having looked. I also remember trying to keep it to a bare minimum, as I expected Introduction to be the frequently-accessed first-point-of-contact, not a one-off throwaway, which it's been turned into. The whole Philosophy of LyX stuff belongs in either the UG or the Tutorial, not in Intro) - Mainly, though, it's due to a failing in my vision: The Reference was supposed to be the search for j-random-feature, find which docs cover it index you seem to be missing. Reference was supposed to be a community-wide maintenance effort. It wouldn't be pretty, but it'd be thorough. I even included a sample, Here's how to add an entry, section in the thing. But no... no one bothered to start there. No. Too busy painting the house to bother replacing the rotting clapboards they're trying to paint over... Not all of the menus are described because one doesn't need to know what they all are. But that's the intention of a UserGuide! Now you're being unfair by taking what I said out of context. You do not need to know what they all are all at once in order to use LyX as an effective writing tool. You do not need faxing in order to write a paper, and playing around with character formats is a Great Time Black Hole, one regularly used to avoid doing the real work: writing the content. Another example: After three years using LyX, I now found out what the menu Navigate-Bookmarks does and how I can change the number of available bookmarks. This feature is very useful for me, but wasn't described in the docs. 1. Was added in the past year or so. We've had no docteam in that time. 2. Useful, yes. Necessary, no. You don't need a navigation tool to figure out what you want to say in the regular flow of text, and what you want to put in a bullet list. Which is rather the whole point of LyX: forget the exterior frills. Focus on the content. (Read at bottom for some related gripes (not at you).) The User's Guide was supposed to contain only those features that give you the advantage of focussing on content over appearance. (sigh But I said that before, several times, and you ignored me, several times. Why should now be any different...) As you can see undescribed menus won't be used. and ironic comments. (These comments are often funny but shouldn't be part of a manual.) ...because manuals should be as dry as dust, and so boring that nobody looks at them? Yes of course ;-) I mean commands like If you use Export-PostScript you can start drinking a coffee (translated from the german docs). If users don't laugh about it, it scares them off. That's poor translation. Read the original English. Which, now that I think of it, may be a bit dated considering modern processor speed. Nobody read a UserGuide from the beginning to the end. Except of the tutorial, docs are used as reference book. Because most of them are as dry as dust, boring, and treat the reader like a lobotomized mentally-disabled-person. I've already done adding some of the customization stuff to the UserGuide. In my opinion sections like the one describing the
Re: [rework docs] reasons, plans, questions
On Wed, Jan 12, 2005 at 05:20:49PM -0800, Jeremy C. Reed wrote: On Wed, 12 Jan 2005, John Weiss wrote: Use a separate doc and include it via a master doc. I was thinking about that. Other than the book will have a lot of redundant information. Yes, that is a problem, isn't it? One of the primary design constraints of the LyX Docs is that it be readable both in print and online. It serves both of these purposes. I understand. : : A master document including the parts is a good idea; maybe the individual parts can still be rewritten some so they don't repeat to much. Alas, no. The repetition was added, intentionally, after I was told that I had the wrong balance. See, I originally came up with a compromise: just enough repetition so that a user wouldn't need to go flipping to a different document *most* of the time. Keeping repetition to a minimum, referencing other docs, was a maintenance strategy (less repetition == less editing when repeated parts need to change). However, the balance I came up with assumed that our users remember things as well as I do ... or used to 7 years ago :P ... which wasn't correct. So others later added in more repetition. Change the individual docs to reduce the repetition, and you'll soon be hearing shrieks of pain from LyX users. This is, yet again, one of those compromises we made between read online and read printed version. -- John Weiss
Re: [rework docs] reasons, plans, questions
On Thu, Jan 13, 2005 at 10:07:27AM +0100, Jean-Marc Lasgouttes wrote: > > "Uwe" == Uwe Stöhr <[EMAIL PROTECTED]> writes: > > Uwe> John Weiss wrote: > >> Doesn't follow a strucutred concept, eh? Maybe you should read the > >> mailling list archives before insulting me. > > Uwe> Sorry I wouldn't harm anybody. I didn't know that there is an > Uwe> active doc maintainer. I asked that on the docs- list a year ago > Uwe> and nobody replied. Are you the current doc maintainer? > > You are right that there is no active documentation maintainer, and it > has been so for several years. John takes offense at the fact that you > described his cherished baby as 'not structured'... No, more that he's saying no structure exists, when historical evidence (and my own memory of all that work!) points to the contrary. > So the conclusion is that your activity on the docs is much needed and > very appreciated, but you should not criticize John's work, at least > in public ;) Not at all! If my original design plan for the docs has drifted too far from present needs, then by all means, Refactor Away! Which is exactly what we do with the code itself. Just be sure not to repeat the Mistakes of the Past as you change things. *That* drives me nutz.;) -- John Weiss
Re: [rework docs] reasons, plans, questions
On Thu, Jan 13, 2005 at 03:34:24AM +0100, Uwe Stöhr wrote: > John Weiss wrote: > > >Doesn't follow a structured concept, eh? > >Maybe you should read the mailling list archives before insulting me. > > Sorry I wouldn't harm anybody. I didn't know that there is an active doc > maintainer. I asked that on the docs- list a year ago and nobody replied. > Are you the current doc maintainer? Sure, go ahead and be snide. I suppose I deserve it... No, Uwe, there's no one actively maintaining the docs. There hasn't been for a few years now. But that could be for two reasons: (1) I and my helpers did our jobs right 7 years ago and came up with something which, while scratched and dinged up in places, is still servicable. Or (2) I didn't do my job right and the docs are so bad-off as to be useless, yet the User community is afraid to take on the daunting task of writing new ones. I don't subscribe to the LyX user's list (too much traffic, and I have enough trouble keeping up with the devel & docs lists these days), so I'm not hearing the howls of pain caused by the existing docs that you seem to be. > I missed a structured concept in that way, that I often have to search > in all three parts, the UserGuide, Customization and Extended for > keywords to find the information. For a normal user it is often not > clear what is extended or what might be in the UserGuide. - Partly, this is semantics. You should've seen the Great Naming Debate that went on for "User Guide" and "Extended". Boils down, again, to having an international user base who put slightly different connotations on English words depending on what they translate them to in their heads. You are not now, nor ever will fix that, Uwe. - Partly, its changes introduced to the "Introduction.lyx" manual. (I don't remember it being as long as what I see right now, just having looked. I also remember trying to keep it to a bare minimum, as I expected "Introduction" to be the frequently-accessed first-point-of-contact, not a one-off throwaway, which it's been turned into. The whole "Philosophy of LyX" stuff belongs in either the UG or the Tutorial, not in Intro) - Mainly, though, it's due to a failing in my vision: The Reference was supposed to be the "search for j-random-feature, find which docs cover it" index you seem to be missing. Reference was supposed to be a community-wide maintenance effort. It wouldn't be pretty, but it'd be thorough. I even included a sample, "Here's how to add an entry," section in the thing. But no... no one bothered to start there. No. Too busy painting the house to bother replacing the rotting clapboards they're trying to paint over... > >Not all of the menus are described because one doesn't need to know > >what they all are. > > But that's the intention of a UserGuide! Now you're being unfair by taking what I said out of context. You do not need to know what they all are all at once in order to use LyX as an effective writing tool. You do not need faxing in order to write a paper, and playing around with character formats is a Great Time Black Hole, one regularly used to avoid doing the real work: writing the content. > Another example: After three years using LyX, I now found out what the > menu Navigate->Bookmarks does and how I can change the number of > available bookmarks. This feature is very useful for me, but wasn't > described in the docs. 1. Was added in the past year or so. We've had no docteam in that time. 2. Useful, yes. Necessary, no. You don't need a navigation tool to figure out what you want to say in the regular flow of text, and what you want to put in a bullet list. Which is rather the whole point of LyX: forget the exterior frills. Focus on the content. (Read at bottom for some related gripes (not at you).) The User's Guide was supposed to contain only those features that give you the advantage of focussing on content over appearance. ( But I said that before, several times, and you ignored me, several times. Why should now be any different...) > As you can see undescribed menus won't be used. > > >>and ironic comments. (These comments are often funny but > >>shouldn't be part of a manual.) > > > >...because manuals should be as dry as dust, and so boring that nobody > >looks at them? > > Yes of course ;-) I mean commands like "If you use Export->PostScript > you can start drinking a coffee" (translated from the german docs). If > users don't laugh about it, it scares them off. That's poor translation. Read the original English. Which, now that I think of it, may be a bit dated considering modern processor speed. > Nobody read a UserGuide from the beginning to the end. Except of the > tutorial, docs are used as reference book. Because most of them are as dry as dust, boring, and treat the reader like a lobotomized mentally-disabled-person. > I've already done adding some of the customization stuff to the >
Re: [rework docs] reasons, plans, questions
On Wed, Jan 12, 2005 at 05:20:49PM -0800, Jeremy C. Reed wrote: > On Wed, 12 Jan 2005, John Weiss wrote: > > > Use a separate doc and include it via a master doc. > > I was thinking about that. Other than the book will have a lot of > redundant information. Yes, that is a problem, isn't it? > > One of the primary design constraints of the LyX Docs is that it be > > readable both in print and online. It serves both of these purposes. > > I understand. : : > A master document including the parts is a good idea; maybe the individual > parts can still be rewritten some so they don't repeat to much. Alas, no. The repetition was added, intentionally, after I was told that I had the wrong balance. See, I originally came up with a compromise: just enough repetition so that a user wouldn't need to go flipping to a different document *most* of the time. Keeping repetition to a minimum, referencing other docs, was a maintenance strategy (less repetition ==> less editing when repeated parts need to change). However, the balance I came up with assumed that our users remember things as well as I do ... or used to 7 years ago :P ... which wasn't correct. So others later added in more repetition. Change the individual docs to reduce the repetition, and you'll soon be hearing shrieks of pain from LyX users. This is, yet again, one of those compromises we made between "read online" and "read printed version". -- John Weiss
Re: [rework docs] reasons, plans, questions
Uwe == Uwe Stöhr [EMAIL PROTECTED] writes: Uwe John Weiss wrote: Doesn't follow a strucutred concept, eh? Maybe you should read the mailling list archives before insulting me. Uwe Sorry I wouldn't harm anybody. I didn't know that there is an Uwe active doc maintainer. I asked that on the docs- list a year ago Uwe and nobody replied. Are you the current doc maintainer? You are right that there is no active documentation maintainer, and it has been so for several years. John takes offense at the fact that you described his cherished baby as 'not structured'... So the conclusion is that your activity on the docs is much needed and very appreciated, but you should not criticize John's work, at least in public ;) JMarc
Re: [rework docs] reasons, plans, questions
> "Uwe" == Uwe Stöhr <[EMAIL PROTECTED]> writes: Uwe> John Weiss wrote: >> Doesn't follow a strucutred concept, eh? Maybe you should read the >> mailling list archives before insulting me. Uwe> Sorry I wouldn't harm anybody. I didn't know that there is an Uwe> active doc maintainer. I asked that on the docs- list a year ago Uwe> and nobody replied. Are you the current doc maintainer? You are right that there is no active documentation maintainer, and it has been so for several years. John takes offense at the fact that you described his cherished baby as 'not structured'... So the conclusion is that your activity on the docs is much needed and very appreciated, but you should not criticize John's work, at least in public ;) JMarc
Re: [rework docs] reasons, plans, questions
John Weiss <[EMAIL PROTECTED]> writes: | On Sat, Jan 08, 2005 at 08:35:11PM +0100, Uwe Stöhr wrote: >> >> Reasons: >> First I just wanted to update the documentation for LyX QT 1.3.x and >> make a bit more platform independent. But while working on the >> UserGuide, I realized that it is really out of date. The last complete >> rework was done in 2000 for the LyX 1.0.x series. In the meantime many >> updates and new sections were added. But the documentation still misses >> many informations and doesn't follow a structured concept. > | Doesn't follow a strucutred concept, eh? > | Maybe you should read the mailling list archives before insulting me. Come on... | | ...because *everyone* is German and therefore uses a German-centric | LaTeX class like koma-script. | We don't need it. -- Lgb
Re: [rework docs] reasons, plans, questions
On Sun, Jan 09, 2005 at 10:34:29PM +0100, Uwe Stöhr wrote: Andre Poenitz wrote: Indeed. Having it in the UserGuide only serves people masochistic enough to read it either as .lyx in a text editor before installation or after installation to see what might have sped up the installation... You are right, I dropped this now. I think what you want to do instead, Uwe, is to add a chapter to Customization roughly outlining what all of the different addons are, by category, and why one might want them. -- John Weiss
Re: [rework docs] reasons, plans, questions
On Mon, Jan 10, 2005 at 09:41:56AM -0800, Jeremy C. Reed wrote: I though if the goal is to have a printed book, then the installation should be covered also. Use a separate doc and include it via a master doc. Jeremy, Uwe, you guys are MAKING ME VERY NERVOUS with your near-fixation on making a printable version to the exclusion of everything else. One of the primary design constraints of the LyX Docs is that it be readable both in print and online. It serves both of these purposes. The LyX Developers even added a feature into LyX ... the infamous menu arrow special character ... to serve this very purpose. Ignore online readability/navigability at your peril! -- John Weiss
Re: [rework docs] reasons, plans, questions
On Wed, 12 Jan 2005, John Weiss wrote: Use a separate doc and include it via a master doc. I was thinking about that. Other than the book will have a lot of redundant information. Jeremy, Uwe, you guys are MAKING ME VERY NERVOUS with your near-fixation on making a printable version to the exclusion of everything else. One of the primary design constraints of the LyX Docs is that it be readable both in print and online. It serves both of these purposes. I understand. The LyX Developers even added a feature into LyX ... the infamous menu arrow special character ... to serve this very purpose. Ignore online readability/navigability at your peril! A master document including the parts is a good idea; maybe the individual parts can still be rewritten some so they don't repeat to much. Jeremy C. Reed technical support remote administration http://www.pugetsoundtechnology.com/
Re: [rework docs] reasons, plans, questions
On Sun, Jan 09, 2005 at 10:34:29PM +0100, Uwe Stöhr wrote: > Andre Poenitz wrote: > > >Indeed. Having it in the UserGuide only serves people masochistic enough > >to read it either as .lyx in a text editor before installation or after > >installation to see what might have sped up the installation... > > You are right, I dropped this now. I think what you want to do instead, Uwe, is to add a chapter to Customization roughly outlining what all of the different addons are, by category, and why one might want them. -- John Weiss
Re: [rework docs] reasons, plans, questions
On Mon, Jan 10, 2005 at 09:41:56AM -0800, Jeremy C. Reed wrote: > > I though if the goal is to have a printed book, then the installation > should be covered also. Use a separate doc and include it via a master doc. Jeremy, Uwe, you guys are MAKING ME VERY NERVOUS with your near-fixation on making a printable version to the exclusion of everything else. One of the primary design constraints of the LyX Docs is that it be readable both in print and online. It serves both of these purposes. The LyX Developers even added a feature into LyX ... the infamous "menu arrow" special character ... to serve this very purpose. Ignore online readability/navigability at your peril! -- John Weiss
Re: [rework docs] reasons, plans, questions
On Wed, 12 Jan 2005, John Weiss wrote: > Use a separate doc and include it via a master doc. I was thinking about that. Other than the book will have a lot of redundant information. > Jeremy, Uwe, you guys are MAKING ME VERY NERVOUS with your > near-fixation on making a printable version to the exclusion of > everything else. > > One of the primary design constraints of the LyX Docs is that it be > readable both in print and online. It serves both of these purposes. I understand. > The LyX Developers even added a feature into LyX ... the infamous > "menu arrow" special character ... to serve this very purpose. > > Ignore online readability/navigability at your peril! A master document including the parts is a good idea; maybe the individual parts can still be rewritten some so they don't repeat to much. Jeremy C. Reed technical support & remote administration http://www.pugetsoundtechnology.com/
Re: [rework docs] reasons, plans, questions
John Weiss wrote: Doesn't follow a strucutred concept, eh? Maybe you should read the mailling list archives before insulting me. Sorry I wouldn't harm anybody. I didn't know that there is an active doc maintainer. I asked that on the docs- list a year ago and nobody replied. Are you the current doc maintainer? I missed a structured concept in that way, that I often have to search in all three parts, the UserGuide, Customization and Extended for keywords to find the information. For a normal user it is often not clear what is extended or what might be in the UserGuide. But anyway, I added a sectipon with a description of all menus. There are listed the relevant sections describing a menu, so that the user will have a good starting point to search the docs. E.g. not all menus are described and there is no explanation for the icon buttons under the menu bar. Since tooltips will tell you what they do, it becomes obvious which menu items they're shortcuts for. If you don't know the corresponding menu item, then you clearly don't need it yet. That's not right. E.g. I worked with on many documents, but it lasts a year until I found out what the toolbar button "FONT" does. Now that that I know this, it is the button I use the most. Not all of the menus are described because one doesn't need to know what they all are. But that's the intention of a UserGuide! Another example: After three years using LyX, I now found out what the menu Navigate->Bookmarks does and how I can change the number of available bookmarks. This feature is very useful for me, but wasn't described in the docs. As you can see undescribed menus won't be used. and ironic comments. (These comments are often funny but shouldn't be part of a manual.) ...because manuals should be as dry as dust, and so boring that nobody looks at them? Yes of course ;-) I mean commands like "If you use Export->PostScript you can start drinking a coffee" (translated from the german docs). If users don't laugh about it, it scares them off. Nobody read a UserGuide from the beginning to the end. Except of the tutorial, docs are used as reference book. At last I want to merge the Customization and Extended manual. Some of its stuff will be part of the UserGuide. Bad Idea. I suggest you look through the mailing list archives for my earlier emails where I describe the structure of the docs. These two files were split off for a reason. I've already done adding some of the customization stuff to the UserGuide. In my opinion sections like the one describing the preferences should be in the UserGuide. But we should discuss such issues if I've an alpha version ready. Because copy/paste sections and changing layouts could be done easily. I'll concentrate to update the docs and to add more information. I started once with a new layout for the UserGuide in koma-script book format. ...because *everyone* is German and therefore uses a German-centric LaTeX class like koma-script. My experience form the lyx-users list is, that people from very different countries use koma-script. This package doesn't have any german special in its layout, even its letter class uses EN/DIN-norms by default. (only the author is German). I like it for its features like printspace calculation (typearea) or support for caption formatting. (no need for additional packages, like caption or tocbibind) But you should have read till the end of my message: I go back to the standard book class. Right now, I have doubts. I read a lot of high-flying ideas from you, with very little grounding in practicality. Let me give you an example of what I mean by "practicality": The "Customize the X keyboard for non-US-English". We added that because the lists were getting about 2-3 "Hlp Me" messages a month asking for this information. There was a practical reason for adding it to the docs, so in it went. Describing additional things like setup X-issues will hamper it keeping the docs up to date. Things changes so fast - especially every Linux distribution is different. Therefore I want to get rid of it. As you mentioned the lyx-users list, you should browse it through the last years to have an impression about actual problems. There are almost the same questions: - Why does the font look pixeld in the pdf-output. - Formula issues - encodings (unicode) - bibtex issues And these are the ones I add to the docs now. So why I'm high-flying? The book is an idea, but not to be done alone and within two months. I just asked about opinions and experiences with that. Possibly the book will never be published. There were practical reasons for the division of the docs. I've never said, that I want to merge them all together. And, in the case of the docs, can you put yourself and your own agenda (printable book) aside and make decisions grounded in practical, broad-user-community-consensus-based reasons? I introduced LyX to my institute and also to elder people - mostly Win-users. The last time I send 50
Re: [rework docs] reasons, plans, questions
On Sun, Jan 09, 2005 at 04:11:09PM +, John Levon wrote: On Sat, Jan 08, 2005 at 08:35:11PM +0100, Uwe St?hr wrote: The UserGuide will also have a short section about needed programs and install issues for the platforms Linux/Unix, Mac and Win. IMO, whilst such docs would be great, the User Guide is the wrong place for it. I'd prefer such stuff to be on the website / wiki, plus a plain ASCII file in the tarball Indeed. Having it in the UserGuide only serves people masochistic enough to read it either as .lyx in a text editor before installation or after installation to see what might have sped up the installation... Andre'
Re: [rework docs] reasons, plans, questions
On Sun, Jan 09, 2005 at 03:58:08PM +0100, Uwe Stöhr wrote: BTW. If LyX 1.4 is such a big step to the future why don't we name it LyX 2.0? Because most of the infrastructure changes will bear user visible fruit only in the next release, or even later. Btw2 Is it planned to release LyX 1.4 with a GTK GUI? Depends on the release date. If that's 'soonish', probably not, otherwise i depends on th GTK frontend to catch up... Andre'
Re: [rework docs] reasons, plans, questions
Uwe == Uwe Stöhr [EMAIL PROTECTED] writes: Uwe Georg Baum wrote: I see one problem: What happens to the 1.4 documentation? At some point one would need to merge your changes back. Did you consider to leave 1.3 as is and modify 1.4 instead? This would avoid some additional work. IMHO we should not put too much effort in 1.3 anymore but concentrate on getting 1.4 ready. Uwe I started with the UserGuide found in the CVS under lib/docs. I Uwe thaught it is the version for LyX 1.4. If not where can I get the Uwe right one? So, to make things clear, your target version is 1.4.0, right? JMarc
Re: [rework docs] reasons, plans, questions
Jean-Marc Lasgouttes wrote: So, to make things clear, your target version is 1.4.0, right? Yes it is. regards Uwe
Re: [rework docs] reasons, plans, questions
On Mon, Jan 10, 2005 at 09:41:56AM -0800, Jeremy C. Reed wrote: On Sun, 9 Jan 2005, [ISO-8859-1] Uwe Sthr wrote: Andre Poenitz wrote: Indeed. Having it in the UserGuide only serves people masochistic enough to read it either as .lyx in a text editor before installation or after installation to see what might have sped up the installation... You are right, I dropped this now. I though if the goal is to have a printed book, then the installation should be covered also. Putting that in a book about lyx seems to be the right thing, but it still doesn't need to be in the UserGuide. A book can, for example, include the userguide as one part and installation information as another. Or, as an alternative, the userguide could include verbatim the textfile that describes installation. Helge Hafting
Re: [rework docs] reasons, plans, questions
On Sun, Jan 09, 2005 at 04:11:09PM +, John Levon wrote: > On Sat, Jan 08, 2005 at 08:35:11PM +0100, Uwe St?hr wrote: > > > The UserGuide will also have a short section about needed programs > > and install issues for the platforms Linux/Unix, Mac and Win. > > IMO, whilst such docs would be great, the User Guide is the wrong place > for it. I'd prefer such stuff to be on the website / wiki, plus a plain > ASCII file in the tarball Indeed. Having it in the UserGuide only serves people masochistic enough to read it either as .lyx in a text editor before installation or after installation to see what might have sped up the installation... Andre'
Re: [rework docs] reasons, plans, questions
On Sun, Jan 09, 2005 at 03:58:08PM +0100, Uwe Stöhr wrote: > BTW. If LyX 1.4 is such a big step to the future why don't we name it > LyX 2.0? Because most of the infrastructure changes will bear user visible fruit only in the next release, or even later. > Btw2 Is it planned to release LyX 1.4 with a GTK GUI? Depends on the release date. If that's 'soonish', probably not, otherwise i depends on th GTK frontend to catch up... Andre'
Re: [rework docs] reasons, plans, questions
> "Uwe" == Uwe Stöhr <[EMAIL PROTECTED]> writes: Uwe> Georg Baum wrote: >> I see one problem: What happens to the 1.4 documentation? At some >> point one would need to merge your changes back. Did you consider >> to leave 1.3 as is and modify 1.4 instead? This would avoid some >> additional work. IMHO we should not put too much effort in 1.3 >> anymore but concentrate on getting 1.4 ready. Uwe> I started with the UserGuide found in the CVS under lib/docs. I Uwe> thaught it is the version for LyX 1.4. If not where can I get the Uwe> right one? So, to make things clear, your target version is 1.4.0, right? JMarc
Re: [rework docs] reasons, plans, questions
Jean-Marc Lasgouttes wrote: So, to make things clear, your target version is 1.4.0, right? Yes it is. regards Uwe
Re: [rework docs] reasons, plans, questions
On Mon, Jan 10, 2005 at 09:41:56AM -0800, Jeremy C. Reed wrote: > On Sun, 9 Jan 2005, [ISO-8859-1] Uwe Stöhr wrote: > > > Andre Poenitz wrote: > > > > > Indeed. Having it in the UserGuide only serves people masochistic enough > > > to read it either as .lyx in a text editor before installation or after > > > installation to see what might have sped up the installation... > > > > You are right, I dropped this now. > > I though if the goal is to have a printed book, then the installation > should be covered also. > Putting that in a book about lyx seems to be the right thing, but it still doesn't need to be in the UserGuide. A book can, for example, include the userguide as one part and installation information as another. Or, as an alternative, the userguide could include verbatim the textfile that describes installation. Helge Hafting
Re: [rework docs] reasons, plans, questions
Hi Uwe, I would rework the Tutorial and the UserGuide. The UserGuide will also have a short section about needed programs and install issues for the platforms Linux/Unix, Mac and Win. Hmmm... Does this make sense? If the user is able to read the UserGuide, he already managed to install LyX. Installation issues should be described in the README files provided with the source code. I started once with a new layout for the UserGuide in koma-script book format. As koma-script is no longer part of the default installation of VTeX and MikTeX, I returned back to the standard book class. Very interesting. Was komascript replaced by some new classes? Publishing a book could help to reach more people and could possibly help to pay the bills for one of the next developer meeting. What do you think about it? Great idea, in principle. However, I wonder whether the audience is broad enough. Has anybody ever counted to the number of LyX downloads? Do we have 100, 1.000, 10.000 or even more users? I changed the menu names in the documentation to the one used in LyX QT 1.3.x. I hope that they are the same as in LyX XForms. If this isn't the case, we should make them as uniform as possible for all GUIs. LyX 1.4 support the branch inset concept. You can put different texts in different branches, e.g. one branch for XForms and one branch for Qt. However, personally, I think it is best to stick to the Qt frontend only. IIRC even Angus admits that Qt is the GUI of the future. What I did/do: The rework of the Introduction is done. I currently working on the sections describing all menus and icon buttons. Please note that LyX 1.4 will look _substantially_ different from LyX 1.3. IMHO you should concentrate on LyX 1.4 and leave LyX 1.3 as it is. Kind regards, Michael
Re: [rework docs] reasons, plans, questions
Andre Poenitz wrote: [...] As koma-script is no longer part of the default installation of VTeX and MikTeX, [Why btw? Sounds like a strange decision ...] The author of koma-script complained about the inclusion of his package to MikTeX. MikTeX has a different (but very user friendly) package handling in comparison to teTeX that the MikTeX people wouldn't change. Therefore MikTeX comes with a slightly older version of koma-script (because the old license of the package allows it) but not in the smallest (basic) installation. I don't know what happend for VTeX. regards Uwe
Re: [rework docs] reasons, plans, questions
Georg Baum wrote: I see one problem: What happens to the 1.4 documentation? At some point one would need to merge your changes back. Did you consider to leave 1.3 as is and modify 1.4 instead? This would avoid some additional work. IMHO we should not put too much effort in 1.3 anymore but concentrate on getting 1.4 ready. I started with the UserGuide found in the CVS under lib/docs. I thaught it is the version for LyX 1.4. If not where can I get the right one? I don't think that install issues belong into the user guide. IMHO they would be better put in an installation manual (that all users of prepackaged versions like the application bundle on Mac or .rpm, .deb etc can ignore). Or maybe put the install issues into an appendix. You are right. I wrote a section about installing under win and it takes only a half page. That should be enough. A detailed description could be indeed added to a special install manual. regards Uwe
Re: [rework docs] reasons, plans, questions
Michael Schmitt wrote: The UserGuide will also have a short section about needed programs and install issues for the platforms Linux/Unix, Mac and Win. Hmmm... Does this make sense? If the user is able to read the UserGuide, he already managed to install LyX. Installation issues should be described in the README files provided with the source code. Of course you are right. I want only a _short_ section with the programs needed for proper work (a half page should be enough). I noticed that some users managed to install LyX but forgot to install a pdf-viewer or ghostscript. Publishing a book could help to reach more people and could possibly help to pay the bills for one of the next developer meeting. What do you think about it? Great idea, in principle. However, I wonder whether the audience is broad enough. Has anybody ever counted to the number of LyX downloads? Do we have 100, 1.000, 10.000 or even more users? Interesting question. But the audience is bigger than the counted downloads from lyx.org. All LyX and Linux users I know use the version shipped with the Linux distribution. I know that publishing a book is not as easy as it seems and is not the primary goal for now. I came on the idea by Dante's book series. They published the koma-script manual and a beautiful book about PStricks. The latter is written by Herbet Voss. I bought them because they are very cheap and a printed book is easier to read than an online version. Please note that LyX 1.4 will look _substantially_ different from LyX 1.3. IMHO you should concentrate on LyX 1.4 and leave LyX 1.3 as it is. This is what I want. But I found only the old UserGuide in CVS. As I'm using Windows (there are many different reasons) I wasn't able to compile a CVS version. If Angus completed the support for LyX under Win I could try it again. Or Someone could send me a CVS binary. This binary needn't to be usable, only that I know how it looks. BTW. If LyX 1.4 is such a big step to the future why don't we name it LyX 2.0? Btw2 Is it planned to release LyX 1.4 with a GTK GUI? regards Uwe
Re: [rework docs] reasons, plans, questions
Uwe Stöhr wrote: Andre Poenitz wrote: [...] As koma-script is no longer part of the default installation of VTeX and MikTeX, [Why btw? Sounds like a strange decision ...] The author of koma-script complained about the inclusion of his package to MikTeX. no, Markus never complained, that his package is part of miktex. He doesn't like it, when his distribution is split into several parts, just as MiKTeX does. MikTeX has a different (but very user friendly) package handling in comparison to teTeX that the MikTeX people wouldn't change. the package handling of MiKTeX is not user-friendly! is is _better_ than nothing, as for teTeX, but MiKTeX ghandles only packages, which are part of the MiKTeX base, other packages must be installed by the user. The problem is not KOMAscript and not MiKTeX, the problem are the two maintainers ... Therefore MikTeX comes with a slightly older version of koma-script (because the old license of the package allows it) but not in the smallest (basic) installation. I don't know what happend for VTeX. VTeX has nothing to do with MiKTeX ... Herbert -- http://TeXnik.de/ http://PSTricks.de/ ftp://ftp.dante.de/tex-archive/info/math/voss/Voss-Mathmode.pdf http://www.dante.de/faq/de-tex-faq/ http://www.tex.ac.uk/cgi-bin/texfaq2html?introduction=yes
Re: [rework docs] reasons, plans, questions
On Sat, Jan 08, 2005 at 08:35:11PM +0100, Uwe St?hr wrote: The UserGuide will also have a short section about needed programs and install issues for the platforms Linux/Unix, Mac and Win. IMO, whilst such docs would be great, the User Guide is the wrong place for it. I'd prefer such stuff to be on the website / wiki, plus a plain ASCII file in the tarball regards john
Re: [rework docs] reasons, plans, questions
Am Sonntag, 9. Januar 2005 15:34 schrieb Uwe Stöhr: I started with the UserGuide found in the CVS under lib/docs. I thaught it is the version for LyX 1.4. If not where can I get the right one? This is correct if it is the HEAD branch. I thought you used 1.3 because you wrote that you wanted to update the 1.3 documentation originally. Georg
Re: [rework docs] reasons, plans, questions
Andre Poenitz wrote: Indeed. Having it in the UserGuide only serves people masochistic enough to read it either as .lyx in a text editor before installation or after installation to see what might have sped up the installation... You are right, I dropped this now. thanks Uwe
Re: [rework docs] reasons, plans, questions
Hi Uwe, I would rework the Tutorial and the UserGuide. The UserGuide will also have a short section about needed programs and install issues for the platforms Linux/Unix, Mac and Win. Hmmm... Does this make sense? If the user is able to read the UserGuide, he already managed to install LyX. Installation issues should be described in the README files provided with the source code. I started once with a new layout for the UserGuide in koma-script book format. As koma-script is no longer part of the default installation of VTeX and MikTeX, I returned back to the standard book class. Very interesting. Was komascript replaced by some new classes? Publishing a book could help to reach more people and could possibly help to pay the bills for one of the next developer meeting. What do you think about it? Great idea, in principle. However, I wonder whether the audience is broad enough. Has anybody ever counted to the number of LyX downloads? Do we have 100, 1.000, 10.000 or even more users? I changed the menu names in the documentation to the one used in LyX QT 1.3.x. I hope that they are the same as in LyX XForms. If this isn't the case, we should make them as uniform as possible for all GUIs. LyX 1.4 support the "branch inset " concept. You can put different texts in different branches, e.g. one branch for XForms and one branch for Qt. However, personally, I think it is best to stick to the Qt frontend only. IIRC even Angus admits that Qt is the GUI of the future. What I did/do: The rework of the Introduction is done. I currently working on the sections describing all menus and icon buttons. Please note that LyX 1.4 will look _substantially_ different from LyX 1.3. IMHO you should concentrate on LyX 1.4 and leave LyX 1.3 as it is. Kind regards, Michael
Re: [rework docs] reasons, plans, questions
Andre Poenitz wrote: [...] As koma-script is no longer part of the default installation of VTeX and MikTeX, [Why btw? Sounds like a strange decision ...] The author of koma-script complained about the inclusion of his package to MikTeX. MikTeX has a different (but very user friendly) package handling in comparison to teTeX that the MikTeX people wouldn't change. Therefore MikTeX comes with a slightly older version of koma-script (because the old license of the package allows it) but not in the smallest (basic) installation. I don't know what happend for VTeX. regards Uwe
Re: [rework docs] reasons, plans, questions
Georg Baum wrote: I see one problem: What happens to the 1.4 documentation? At some point one would need to merge your changes back. Did you consider to leave 1.3 as is and modify 1.4 instead? This would avoid some additional work. IMHO we should not put too much effort in 1.3 anymore but concentrate on getting 1.4 ready. I started with the UserGuide found in the CVS under lib/docs. I thaught it is the version for LyX 1.4. If not where can I get the right one? I don't think that install issues belong into the user guide. IMHO they would be better put in an installation manual (that all users of prepackaged versions like the application bundle on Mac or .rpm, .deb etc can ignore). Or maybe put the install issues into an appendix. You are right. I wrote a section about installing under win and it takes only a half page. That should be enough. A detailed description could be indeed added to a special install manual. regards Uwe
Re: [rework docs] reasons, plans, questions
Michael Schmitt wrote: The UserGuide will also have a short section about needed programs and install issues for the platforms Linux/Unix, Mac and Win. Hmmm... Does this make sense? If the user is able to read the UserGuide, he already managed to install LyX. Installation issues should be described in the README files provided with the source code. Of course you are right. I want only a _short_ section with the programs needed for proper work (a half page should be enough). I noticed that some users managed to install LyX but forgot to install a pdf-viewer or ghostscript. Publishing a book could help to reach more people and could possibly help to pay the bills for one of the next developer meeting. What do you think about it? Great idea, in principle. However, I wonder whether the audience is broad enough. Has anybody ever counted to the number of LyX downloads? Do we have 100, 1.000, 10.000 or even more users? Interesting question. But the audience is bigger than the counted downloads from lyx.org. All LyX and Linux users I know use the version shipped with the Linux distribution. I know that publishing a book is not as easy as it seems and is not the primary goal for now. I came on the idea by Dante's book series. They published the koma-script manual and a beautiful book about PStricks. The latter is written by Herbet Voss. I bought them because they are very cheap and a printed book is easier to read than an online version. Please note that LyX 1.4 will look _substantially_ different from LyX 1.3. IMHO you should concentrate on LyX 1.4 and leave LyX 1.3 as it is. This is what I want. But I found only the old UserGuide in CVS. As I'm using Windows (there are many different reasons) I wasn't able to compile a CVS version. If Angus completed the support for LyX under Win I could try it again. Or Someone could send me a CVS binary. This binary needn't to be usable, only that I know how it looks. BTW. If LyX 1.4 is such a big step to the future why don't we name it LyX 2.0? Btw2 Is it planned to release LyX 1.4 with a GTK GUI? regards Uwe
Re: [rework docs] reasons, plans, questions
Uwe Stöhr wrote: Andre Poenitz wrote: [...] As koma-script is no longer part of the default installation of VTeX and MikTeX, [Why btw? Sounds like a strange decision ...] The author of koma-script complained about the inclusion of his package to MikTeX. no, Markus never complained, that his package is part of miktex. He doesn't like it, when his distribution is split into several parts, just as MiKTeX does. MikTeX has a different (but very user friendly) package handling in comparison to teTeX that the MikTeX people wouldn't change. the package handling of MiKTeX is not user-friendly! is is _better_ than nothing, as for teTeX, but MiKTeX ghandles only packages, which are part of the MiKTeX base, other packages must be installed by the user. The problem is not KOMAscript and not MiKTeX, the problem are the two maintainers ... Therefore MikTeX comes with a slightly older version of koma-script (because the old license of the package allows it) but not in the smallest (basic) installation. I don't know what happend for VTeX. VTeX has nothing to do with MiKTeX ... Herbert -- http://TeXnik.de/ http://PSTricks.de/ ftp://ftp.dante.de/tex-archive/info/math/voss/Voss-Mathmode.pdf http://www.dante.de/faq/de-tex-faq/ http://www.tex.ac.uk/cgi-bin/texfaq2html?introduction=yes
Re: [rework docs] reasons, plans, questions
On Sat, Jan 08, 2005 at 08:35:11PM +0100, Uwe St?hr wrote: > The UserGuide will also have a short section about needed programs > and install issues for the platforms Linux/Unix, Mac and Win. IMO, whilst such docs would be great, the User Guide is the wrong place for it. I'd prefer such stuff to be on the website / wiki, plus a plain ASCII file in the tarball regards john
Re: [rework docs] reasons, plans, questions
Am Sonntag, 9. Januar 2005 15:34 schrieb Uwe Stöhr: > I started with the UserGuide found in the CVS under lib/docs. I thaught > it is the version for LyX 1.4. If not where can I get the right one? This is correct if it is the HEAD branch. I thought you used 1.3 because you wrote that you wanted to update the 1.3 documentation originally. Georg
Re: [rework docs] reasons, plans, questions
On Sat, Jan 08, 2005 at 08:35:11PM +0100, Uwe Stöhr wrote: > Plans: I would rework the Tutorial and the UserGuide. [...] I don't think anybody is going to stop you. Not me at least. > But I want to delete platform specifig stuff like "Configuring the X > keyboard" etc. and ironic comments. (These comments are often funny but > shouldn't be part of a manual.) If they are really funny you could leave them in. As a reality check you might ask one of the regular readers from the Western Islands (where the Pound is still a Pound...). > [...] As koma-script is no longer part of the default installation of > VTeX and MikTeX, [Why btw? Sounds like a strange decision ...] > But if the rework is done, I want to merge the manual files to a > printable koma-script book file using all layout tricks, so that it can > be published as a real book. (I wondered why there is no book about LyX > available.) Publishing a book could help to reach more people and could > possibly help to pay the bills for one of the next developer meeting. > What do you think about it? Not bad. > Questions: > While working on the docs, many questions came in my mind that I would > ask in several other messages to this list. I hope someone can help me. I am not reading lyx-doc. Should I? Andre'
Re: [rework docs] reasons, plans, questions
Andre Poenitz wrote: Indeed. Having it in the UserGuide only serves people masochistic enough to read it either as .lyx in a text editor before installation or after installation to see what might have sped up the installation... You are right, I dropped this now. thanks Uwe
