Re: LyX, wiki and documentation
On Thu, Jan 20, 2005 at 03:22:59PM +0100, Jean-Marc Lasgouttes wrote: > > I thought it could be useful to replace the FAQ. If we could identify > a section of the wiki that can be used as a FAQ, we could generate > FAQ.lyx from there. I though this is something the Wiki is good at > (and also FAQs tend to need only simple formatting). > > Am I wrong? Not at all. FAQ.lyx was originally dead-on-arrival. Mike Ressler added a "real" FAQ sometime in 2000. So FAQ.lyx is now way out of date. Either way, I think it's safe to fold the existing FAQ.lyx into the Wiki and ditch the FAQ.lyx file. -- John Weiss
Re: LyX, wiki and documentation
On Thu, Jan 20, 2005 at 03:50:51PM +0100, [EMAIL PROTECTED] wrote: > On Thu, 20 Jan 2005, Jean-Marc Lasgouttes wrote: > * How would users like to read the FAQ? > ** Users want to read/browse the FAQ as web (wiki) pages. >This requires an internet connection unless we package a local copy of >the web (wiki) pages with the LyX documentation. > ** Users want to read their FAQ.lyx that comes installed with LyX Honestly, I don't think we really need to have the FAQ be a LyX document anymore. HTML pages, possibly generated from the Wiki, should be sufficient. (It's not like web browsers are all that rare anymore.) Keeping the manuals (or certain manuals, at least) as LyX documents does serve a useful purpose, as Christian points out: an example of how-to-do-that in LyX. With that in mind, I could easily see "Customization.lyx" and "Reference.lyx" turned into webpages maintained on the Wiki by the community. The UG, Tutorial, and Intro would all remain tightly-controlled by some Editor-type-peoples. However, the Wiki could have places where the community could contribute corrections and addendums (not new sections, mind you, but new sentences). That just leaves "Extended.lyx", which could probably use new name. Or not. It should, however, have a new organizational structure and contents in the form of journal-entry-like units, thus making it easy for people to contribute new sections. The level of control would be less-tight than UG/Tutorial/et.al., but not totally willy-nilly. Hmmm... maybe my original concept for the Reference Manual is better served by the Wiki. Hmmm... have a fixed template for entries, a well-documented notation (using Wiki markup, of course), and community contribution. Might work. Might work... -- John Weiss
Re: The Official LyXDocProject StyleSheet
On Wed, Jan 19, 2005 at 06:19:55PM +0100, [EMAIL PROTECTED] wrote: > > Hmm... I think we're better of with the text as PDF anyway to be honest. > As it is, we'll still have to watch out for having multiple versions of > the text lying around etc. That, actually, is my preference. I just wasn't sure if it was yours, as well. -- John Weiss
Re: LyX, wiki and documentation
On Sat, Jan 22, 2005 at 03:23:35PM +0100, [EMAIL PROTECTED] wrote: > > Eh.. I don't get "initial launchpad for new sections of the docs." > > Could you expand on what you mean. As a place where the core of a new section/subsection/subsubsection would start its life. Once large enough to become part of the offical manuals, the old FAQ entry could then be replaced with a verbal "see section XYZ of the QRS manual." That's what I meant. > > P.S.: You'll find that I've added several new sections to the Wiki, > > as I mention in another post. It would be nice if someone could take > > my original DocStyle.lyx style sheet and wikify it... > > Eh.. "new sections"... do you mean new pages or a new group? Which pages? Just look for stuff added by "jpw_public_frontiernet_net". > I could probably wikify DocStyle.lyx very easy, which version did you use > when you created the PDF? Was it the one that's in CVS HEAD? Yes, but... > However, if we wikify DocStyle.lyx we need be clear on where we want to > maintain the "original". Should we make changes to the wiki pages or to > DocStyle.lyx? ...for these reasons, I'm beginning to think it's better to just have a PDF version of DocStyle.lyx (and the original *.lyx file) available from the Wiki. Makes maintenance far easier. -- John Weiss
Re: LyX, wiki and documentation
On Sun, Jan 16, 2005 at 01:47:42AM +0100, [EMAIL PROTECTED] wrote: > Hi > > I'd like to ask for some ideas/thoughts on the wiki from a documentation > perspective. Or rather, I'd like some general thougths on what kind of > documentation we would like for LyX, considering that we can have the > documentation in several places these days. : : > However, I hope we should be able to use the collaborative aspect of the > wiki to make it easier for people to contribute to the documentation. For > instance by supplying examples of how LyX can be used. Or by adding FAQ > etc. Hmm... interestingly, when discussion of making an FAQ *originally* occurred (like, back in 1996 or so), I suggested that the FAQ become an initial launchpad for new sections of the docs. The FAQ could then say, "See the of the manual." Or, at least, that was the idea... It never took off, mainly because an FAQ never really went anywhere, mainly due to the static nature of web pages at that time and work involved in creating them. With the change in landscape in the intervening 7+ years, maybe it's time to resurrect that old plan... P.S.: You'll find that I've added several new sections to the Wiki, as I mention in another post. It would be nice if someone could take my original DocStyle.lyx style sheet and wikify it... -- John Weiss
Re: merging documents into User's Guide
On Fri, Jan 14, 2005 at 01:20:29PM +0100, [EMAIL PROTECTED] wrote: > On Thu, 13 Jan 2005, John Weiss wrote: > > > PHEW! Thanks Christian. It's a relief to know that I don't need to > > rewrite all of those emails... again... > > Umm.. I just put a copy of that particular mail, but if you can give me a > pointer to other relevant mails in the archives I could add them as well. > > Actually, just doing a link to a post in the gmane archive is trivial... > (you just add LyxDocPost:552 to create a link to post 552 in the > Doc-list, and something similar for the user and devel lists). Okay then. I'll have to do some archive searching... -- John Weiss
Re: [rework docs] questions part two
On Thu, Jan 13, 2005 at 03:46:00AM +0100, Uwe Stöhr wrote: > John Weiss wrote: > >2. What the heck is a beamer? > > > >Just because you think it's the greatest-thing-since-sliced-bread > >doesn't mean everyone else does. Or even knows it exists. (Your bias > >is showing, Uwe!) > > (Nobody forces you to add caustic comment to your questions.) I blame it on That Horrible Horrible place I quit working for, (from which I fled screaming). That place makes people mean. (That, and I'm lacking sleep. Never a good combo.) > Beamer is a class for creating presentations. It is a new package but > became one of the most popular in the LaTeX community (browse e.g. > comp.text.tex). Beamer is developed to work together with LyX and also > the beamer userguide incorporate LyX. We jaded longtime LyX'ers have seen it all before. First Seminar, then Foils/FoilTeX. Now Beamer. Replacements for that old, creaky kludge known as SLiTeX crop up about 1 per year. For some odd reason, no single one ever seems to take hold. Heavens only knows why. It's not like SLiTeX isn't obtuse, arcane, subpar, and generally awful. If Beamer is the heir-apparent to SLiTeX, trust me, we'll add full support for it to LyX when the time comes. Then we can finally chuck support for that hack, SLiTeX (which we only keep because [a] it's an official part of LaTeX; and [b] too many hidebound professors refuse to learn anything new :P ). > >If it were really all that critical (like e.g. geometry.sty), it'd > >already have integrated LyX support. If it's The Future, the devteam > >will discover it soon enough... > > So I shouldn't make proposals? Proposals are made as questions. You made an assertion. :) -- John Weiss
Re: [rework docs] questions part one
On Fri, Jan 14, 2005 at 10:09:29AM +0100, Lars Gullik Bjønnes wrote:
> John Weiss <[EMAIL PROTECTED]> writes:
>
> We (or I) do not want us to require a
> lot of ERT to make the printed doc look nice, if ERT is needed then we
> are missing features.
That was certainly the case when I last touched the docs, Lars.
There's one feature that we *do* need added: formatting environments
like \begin{fussy}...\end{fussy} or
\begin{flushleft}...\end{flushleft} that span paragraph environment
(or exist for only a few lines inside of one). There are times when
you need to remove justification or hyphenation for only a few lines.
(And, yes, I'm being glib, not thorough, again.)
--
John Weiss
Reviewing the Past [was: [rework docs] reasons, plans, questions]
OTOH, if you're really serious about taking on updating the docs, Uwe, I have some suggestions. First, see where we've been. I've written copious bytes describing the design and goals of the docs. It'd be foolish not to look at that. Wanna know why some part of the docs is the way it is? Ask me; I may even remember. :D Second, take a page from the latest hot programming technique: Refactor, Refactor, Refactor. Do small incremental changes, with frequent reviews in-between. And by "reviews," I mean the user base (as in the user's mailing list). Third, let the user's mailing list guide changes in organization, layout, and underlying design. Get a consensus for changes, both just-completed and planned, from the community at large. Most of the developers (and, soon, me as well) won't have the time to do more than give changes a cursory glance. Fourth, Beware Wannaponies! A "Wannaponie": Think of a little girl, jumping up and down, shouting, "I Wanna Ponie! I WANNA PONIE!!!" If you ask people, "what do you want in the docs?" you'll get all sorts of hairbrained Wannaponies, most of them conflicting each others' goals. Remember, docs have a design, too. You'll need to ignore those suggestions that conflict with the design. Just like Lars has to reject patches that conflict with the code design. Fifth, I forget fifth. Vielleicht erinnere ich mich daran spïter... -- John Weiss
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 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 b
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] questions part one
Uwe:
For future reference:
When I was working on this 7 years ago, I added various ERT to ensure
a good-looking print version. (I proofread the "print" version using
ghostscript or xdvi back then.) Of course, someone probably decided
to "be helpful" and remove all of my '\raggedright' and
'\begin{sloppypar}' ... '\end{sloppypar}' ERT. Yet Another Example of
someone focussing on only their own narrow agenda (Ze Online Version
Must Look Perfect) to the detriment of everything else (the print
version, in this case).
Bear in mind that you will need to do proofread a DVI/PS/PDF version
for overly-long lines of code, for justification to go haywire on
some individual lines, and similar print flubs. You'll need to do
some LaTeX tweaking on those. You may also need to elminate old LaTeX
tweaks that are no longer relevant due to inserted/deleted
preceeding/following text. Though, I tried to minimize those by using
manual linebreaks on text that went wonky in print.
--
John Weiss
Re: merging documents into User's Guide
On Wed, Jan 12, 2005 at 10:55:06AM +0100, [EMAIL PROTECTED] wrote: > On Tue, 11 Jan 2005, John Weiss wrote: > > I put a copy of John's post here: > http://wiki.lyx.org/pmwiki.php/Devel/MiscNotes > > since they explain the idea behind how the documents are > partitioned. PHEW! Thanks Christian. It's a relief to know that I don't need to rewrite all of those emails... again... > > > Whatever you guys do, please don't expect it to end up back in the > > official docs. We actually had that discussion before. > > Actually I didn't quite understand this bit though.. At the time I wrote that, I was still catching up on my LyX mail backlog. So I hadn't yet read that they wanted to make extensive corrections. I only thought they wanted to merge all 5 docs into one huge book. It's that merger into one book that I was thinking about when I said, "Don't expect that to end up back in the official doc(s)." Sorry i was vague. I blame it on lack of sleep. :) -- John Weiss
Re: [rework docs] include mathed documentation
On Wed, Jan 12, 2005 at 10:31:37AM +0100, [EMAIL PROTECTED] wrote: > On Tue, 11 Jan 2005, [UTF-8] Uwe StïÃïÂïhr wrote: > > > I covers now nearly all math constructs. I want to replace the mathed > > section in the userguide by this documentation. > > In my opinion the tutorial has a very good introduction to mathed: It > > explains navigating in formulas, the math-panel and the most common used > > constructs (fractions etc.). So that we could go deeper in the > > userguide. Mathed supports so many constructs that aren't explained in > > the docs at the moment. > > > > Are there any objections against this plan? > > I doubt that... the only concern I can think of is that it might be too > much/advanced? That's what I was about to say. We (a Maths professor and myself) intentionally *did* *not* cover all possible mathed features in the User's Guide precisely because of scope. Better to move the more esoteric features into the Extended doc. -- John Weiss
Re: Printer Tutorial chapter?
On Wed, Jan 05, 2005 at 12:36:01AM +0100, Uwe Stöhr wrote: > Jeremy C. Reed schrieb: > > >"The Printer" section in the User's Guide mentions "A Printer Tutorial" > >chapter in the Customization manual. > > > >It is not in the Customization.lyx file (although that does have some > >printing configurations). > > > >Can that reference be removed? > > In my opinion yes, because printers are no part of LyX and the printer > settings varies from distribution to distribution. (I also want to clean > the docs from platform specific stuff.) > > The printer tutorial was once chapter 6 of the customization.lyx (e.g. > it is still in the german customization.lyx). Aaaand someone just nuked it without being careful to check the other docs. There is history behind the Printer Setup Tutorial. See, waay back in 1996, we didn't have any newfangled CUPS to set up our printers for us. No siree. We had to do it by hand. Even those "auto-installers" tha existed were nothing more than scripts that put the "by-hand" steps, for a limited number of printers, into a black box. The print quality was usually horrible. So, I wrote a, "how to put together GhostScript+lpr+LyX" for thse interested. At the time, it WAS a relevant part of LyX. 7 years later, things change. Replace contents of the "Printer Tutorial" section in Customizationlyx with a really-quick set of instructions on how to fire up the CUPS web-interface. Mention CUPS several times, and end with, "Because of the ease of setting up a printer on Linux these days, this section is deprecated and will be removed in the next release of LyX." Only after careful proofreading and pruning of all external mentions in the other LyX manuals would I then remove this section. Well, that's how I'd do it, at least. Prevents the, "Why is this here?" and "Where's this mythical section in SomeOtherManual.lyx?" syndromes that you run smack into here. -- 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] questions part one
On Sat, Jan 08, 2005 at 10:16:19PM +0100, Uwe Stöhr wrote: > > Spellchecker: > In the current version of the UserGuide I found a lot of > ispell-specific stuff that I would get rid of. Does the problems with > ispell described there still exist? Or does everybody replaced ispell by > the "newer and generally better aspell"? You are correct! Any mentions of ispell specifically should be replaced with more general text. You may want to occasionally make reference back to some initial section about spelling where you mention the different flavors of spellchecker out there and any subtleties that a user may have to pay attention to. May I suggest, once you know what your replacement prhases should be, doing a document-wide "Find 'ispell'" on every one of the manuals? Then, once you've finished all your edits, do the "Find 'ispell'" again to make sure you got them all. (This is the very same technique I used 7 years ago. Very good for such global doc-refactors.) -- John Weiss
Re: [rework docs] questions part two
On Sun, Jan 09, 2005 at 04:26:18PM +0100, Uwe Stöhr wrote: > Georg Baum wrote: > > >>As I use LyXWin, could somebody please send me his file > >>"LaTeX-Configuration"? This menu is broken in LyXWin and I need it to > >>describe it in the docs. Thanks. > > > >I guess you don't mean the file that you can get via Help->LaTeX > >Configuration? > > No I mean exactly this one. In case no one's sent you theirs, I'm attaching the one from the laptop. -- John Weiss #LyX 1.3 created this file. For more info see http://www.lyx.org/ \lyxformat 221 \textclass article \language english \inputencoding default \fontscheme default \graphics dvips \paperfontsize 0 \spacing single \papersize Default \paperpackage a4 \use_geometry 0 \use_amsmath 0 \use_natbib 0 \use_numerical_citations 0 \paperorientation portrait \secnumdepth 2 \tocdepth 3 \paragraph_separation indent \defskip medskip \quotes_language english \quotes_times 2 \papercolumns 1 \papersides 1 \paperpagestyle plain \layout Title Inventory of your LaTeX configuration \layout Author Automatically generated by LyX (do not edit). \layout Date October 5, 2004 \layout Standard This file describes the different LaTeX add-ons that LyX can handle. Below you'll find six sections: \layout Enumerate Some basic details about your LaTeX installation. In particular, you should make sure that your version of LaTeX is recent enough. \layout Enumerate Some common fonts that LyX knows about. This is rather sparse at the moment. \layout Enumerate The document classes that should be standard on any LaTeX implementation. This section is only here for completeness. \layout Enumerate Some optional document classes that LyX knows about. If one of these is marked as missing (the \begin_inset Quotes eld \end_inset Found \begin_inset Quotes erd \end_inset item is no) and you need its functionality, you can grab it at your nearest CTAN ftp site \begin_inset Foot collapsed true \layout Standard The participating hosts in the Comprehensive TeX Archive Network are: \layout LyX-Code ftp://ftp.dante.de/tex-archive \layout LyX-Code ftp://ctan.tug.org/tex-archive \layout LyX-Code ftp://ftp.tex.ac.uk/tex-archive \layout Standard There are also a zillion mirror sites which are listed at the three primary sites. \end_inset at the location indicated in the \begin_inset Quotes eld \end_inset CTAN \begin_inset Quotes erd \end_inset item. Note that only detected document classes can be selected as document layouts in LyX. \layout Enumerate The packages that have been stamped \begin_inset Quotes eld \end_inset required \begin_inset Quotes erd \end_inset by the LaTeX maintainers. These ones should definitely be present, but you may not have some of them if your LaTeX distribution is a bit old. \layout Enumerate Some packages that LyX uses when you try to change the margins of your document. The detection of these items does not yet affect the options available inside LyX. \layout Enumerate Some common LaTeX packages that you might need with LyX, and you might also want to add to your LaTeX installation. The detection of these items does not yet affect the options available inside LyX. \layout Standard Note that most of these packages will be available if you use a modern TeX distribution such as teTeX. If you decide to install one of the missing items, you should tell LyX about it. After the installation, please use the menu entry \family sans \bar under O \bar default ptions\SpecialChar \menuseparator \bar under R \bar default econfigure \begin_inset Foot collapsed true \layout Standard or, if you want to change the system-wide settings, issue the command \family typewriter ./configure \family default from the LyX system directory (by default \family typewriter /usr/local/lib/lyx/ \family default ) \end_inset and reload this file to see if the new package was recognized. If the \begin_inset Quotes eld \end_inset Found \begin_inset Quotes erd \end_inset items read \begin_inset Quotes eld \end_inset ??? \begin_inset Quotes erd \end_inset , it means that LyX could not do the inventory of your LaTeX configuration for some reason. If you are using teTeX, it might be that the new package you installed is not found. This is because you forgot to run the command \family typewriter texhash \family default , which tells teTeX to update its own configuration. \layout Section LaTeX version currently in use \layout Standard The LaTeX version that LyX will use is: \family typewriter 2001/06/01 \family default . Note that, for best results, you should be using at least LaTeX release \family typewriter 1995/12/01 \family default \begin_inset Foot collapsed true \layout Standard In case it is not clear to you, this number is the date at which the version has been released. \end_inset . In fact, earlier vers
Re: [rework docs] questions part two
On Sun, Jan 09, 2005 at 12:56:11PM +0100, Georg Baum wrote: > Am Samstag, 8. Januar 2005 22:43 schrieb Uwe Stöhr: > > I want the example and template LyX files that comes with the beamer > > package to be added to LyX CVS. These files works very well and the > > author of course allows this. Is this possible or are there some > > objections? > > I don't think that it is worth the effort: I concur: 1. External LaTeX packages have no place in LyX. Lars/Asger/Jean-Marc and a cast-of-thousands worked long and hard to ensure we'd never need to do this (hence the whole LaTeX-Config engine & autogenerated manual). Why resurrect a long-rejected bad idea? 2. What the heck is a beamer? Just because you think it's the greatest-thing-since-sliced-bread doesn't mean everyone else does. Or even knows it exists. (Your bias is showing, Uwe!) If it were really all that critical (like e.g. geometry.sty), it'd already have integrated LyX support. If it's The Future, the devteam will discover it soon enough... -- John Weiss
Re: [rework docs] reasons, plans, questions
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. > E.g. not all menus are described and there is no explanation for the > icon buttons under the menu bar. Ignoring the toolbar was a strategic move. 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. Why are you wasting time messing around with arcane features? Get back to work on that document you're writing! ;) Not all of the menus are described because one doesn't need to know what they all are. One only needs to know where to find the features that one'll use most frequently while writing your average document. Again, a stragetic move, and one to give the docs a clearly-defined structure. I do agree, however, that 4 years of drift have rendered the documented menu locations of many features wrong. That certainly needs to be corrected. > Plans: > I would rework the Tutorial and the UserGuide. > The UserGuide would contain a section with an overview of all menus > and icon buttons. There is a chapter in the Reference manual for this. That is the logical place for it, as I said in the original description of the documents' strucutre. > But I want to delete platform specifig stuff like "Configuring the X > keyboard" etc. "Configuring the X keyboard" could probably go. Life on Linux & X has improved rather significantly in the 7 years since we added that. > 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? > 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 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. Uwe, if you are going to do this, and you want something that ALL of us can use, you need to start looking at the docs through the eyes of all of the users, not just from your own point of view. This is why I'm so critical. (While editor, I was equally critical of contributors for exactly the same reasons when they veered off course into their own narrow perspective.) 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. There were practical reasons for the division of the docs. There were practical reasons for the names of the docs. I didn't personally agree with some of the names, but went with those changes, anyway, because my suggestions didn't convey the proper connotations to the wider audience of LyX users. As much as we'd all love to have someone, anyone, updating the docs, I have to play Lars here for a sec and ask: are you overdesigining? Do we really need this-or-that feature you want to add? 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? -- John Weiss
Re: [rework docs] questions part two
On Sun, Jan 09, 2005 at 03:12:07PM +0100, Uwe Stöhr wrote: > I wrote: > > >The menu Navigate -> Refs seems to be broken. I expect that this menu > >let me jump from cross- and citation-reference to the next, but nothing > >happens. > > Sorry. The menu works., but it doesn't jump from reference to reference. > It jumps from one label to the next. So the menu name is a bit > confusing. It should better have the name "Label". And this is where your job as doc-editor comes in. ;) Describe that thang! -- John Weiss
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: merging documents into User's Guide
WARNING! WARNING! Danger, Will Robinson, Danger! On Tue, Jan 04, 2005 at 02:31:06PM -0800, Jeremy C. Reed wrote: > On Tue, 4 Jan 2005, [ISO-8859-1] Uwe Stïhr wrote: > > In my opinion there should only be two books within the book: the > > tutorial and the userguide. > > > > The tutorial can be called "LyX in three days", what would be an > > appetizer for beginners. (As I once had to learn Delphi, I found a book > > with the chapter "Delphi in 10 hours". Such a chapter eases to start > > with a new program.) > > > > The userguide should contain the extended and customization doc. > > I am thinking of doing the extended and customization document in a second > book. Whatever you guys do, please don't expect it to end up back in the official docs. We actually had that discussion before. In fact, we had that discussion SEVERAL TIMES before. (About every 2 years or so.) When i began the whole Documentation Project waaay back in 1995 or 1996, Matthias Ettrich's original manual was this huge, unnavigable beast. It was so large, there was no way to maintain it effectively. So, it was also hopelessly out of date. You can see that the same has happened again, but this time, it's not nearly as bad, due to the entire division into multiple docs as per my original plan: Introduction: The starting point and jumping-off pad. Added after-the-fact because, what with everyone speaking different mother-tongues, what *I* read when I see "Advanced Features" and what someone else reads when they see that same name for a doc end up being worlds apart. So, The Intro was a way to tell everyone where they needed to go for what they wanted. It was also a place for common introductory info that I found myself copying verbatim into every single manual. Tutorial: Summary of the User's Guide, with step-by-step instructions for timid newbies. User's Guide: Documents the basic, *stable* features. At the time, I was focussed half-and-half on leery LateXperts and resistant emigres from Winblows. Hence the features chosen to grace the UG vs. those that went in "Extended" (a.k.a. "Advanced Features" a.k.a. "Additional Features" a.k.a. ...) Extended: New features, moving-target features, layouts for LaTeX classes favored in certain countries, advanced features like the margin notes and parboxen, et cetera et cetera ad nauseum. Customization: As the name implies. Put in a separate manual because this was, at the time, even MORE of a moving target than the moving-target editing features of LyX. Reference: It was SUPPOSED to be a developer-maintained doc describing all of the more esoteric and arcane aspects of LyX. It ended up just describing the keybindings. And maybe some of the menu bindings. 7 years after I ended my stint as head of the DocProject, the menu layout & keybindings have drifted, and some more features have become standard, but all in all, the docs aren't as out-of-date as they could be, considering the complete lack of any work on them... Oh... And I DEFINITELY suggest that you do "Extended" and "Customization" in their own book. Or maybe books. Put the keybindings in all of your books as Appendicies. Those are my thoughts, and the train is arriving at my stop, so it's approaching time for me to power down this laptop I'm typing on. -- John Weiss
Re: screenshots for User's Guide?
On Wed, Dec 29, 2004 at 02:38:53PM -0800, Jeremy C. Reed wrote: > Has there been any discussion about adding screenshots (or images) to the > LyX User's Guide or other Help documents? > > Jeremy C. Reed > >BSD News, BSD tutorials, BSD links >http://www.bsdnewsletter.com/ Dude, if you wanna contribute the appropriate changes, go for it! Heck, if you wanted to make numerous corrections, you're welcome to it. I long since stopped being doc editor, and will (soon) be migrating over to the C++ coding side. -- John Weiss
Re: license for documentation?
On Fri, Dec 17, 2004 at 11:35:02AM +0100, Asger Kunuk Ottar Alstrup wrote: > On Tue, 14 Dec 2004, Jeremy C. Reed wrote: > > > Does the COPYING file apply to all the doc/ documentation that > > don't have any license in them? > > > > For example, I don't see any republishing or reuse license for > > lib/doc/Customization.lyx. > > It is a good question. When the documentation was written, the concept of > licenses for documentation was not really crystalised yet. So, the > question was never really asked and thus never answered. I believe that a > fair interpretation of intent is that the documentation is GPL. > > > I want to test a print-on-demand service. I want to submit the LyX > > documentation in a single PDF format for a single book. Is this okay? > > I belive that would be ok, but you might try to ask John Weiss who is the > main author of the documentation, and as such he would be the main > copyright holder, In that case, I say that it's under the documentation-equivalent of the GPL. Why? Because waay back when I was editor-in-chief (like, 1996/97), I assumed that all of LyX, including docs, contributed templates, layouts, etc., would be under the GPL. And why did I read it like that? Because I took the license to apply to the entire sourcecode tarball. P.S.: The email address listed for me bounced because my old ISP died over 2 years ago. -- John Weiss
Re: LyX Userguide issues
On Tue, Feb 24, 2004 at 03:39:56PM +0100, Jean-Marc Lasgouttes wrote: > >>>>> "Uwe" == Uwe Stöhr <[EMAIL PROTECTED]> writes: > > Uwe> - use the class 'scrbook' instead of 'book' (scrbook has a better > Uwe> implementation of environments and is recommended by TUG and > Uwe> Dante) > > I agree that scrbook is better than book, but are we sure that > everybody will have a working version of it? I mean, not just > everybody with a two years old linux distribution, but really most > people. > > Never forget that the primary goal of the user guide is to be usable, > and that everybody can just print it without tinkering. EXACTLY! > Uwe> - use A4-paper instead of 'standard' > > How does that print on USletter paper? I thought there were still > quite a lot of people using that... If this is the English version of the Userguide, then you have NO business changing the paper to A4. Why? Because no one in North America will be able to print it. We'll lose the lower half of the page. Aber, wenn es die deutche Version ist, is DIN-A4 okay. -- John Weiss
Re: FAQ
On Tue, Feb 11, 2003 at 05:28:30PM +0100, Christian Ridderström wrote: > Hi > > As you (ought to) know, I've more or less arbitrarily been writing > down some of the questions and answers I've seen on the user's list here: > http://ev-en.org/wiki/moin.cgi/LyxFAQ [snip!] > separately from FAQ.lyx, and if FAQ.lyx is (ever) updated, this entire FAQ > ought to be checked for questions that should go into FAQ.lyx, instead of [snip!] Quick historical remark, Christian: When I originally created FAQ.lyx (during the Great Doc Rewrite of '96), my idea was that *FAQ.lyx* would be one of the two "moving-target" members of the docs. It would shift, change, rearrange as needed and as things moved out of the FAQ into the manuals. My suggestion to you, therefore, would be to do all of your editing in your own version of FAQ.lyx and generate your text FAQ via ASCII-export. You can then submit your FAQ.lyx modifications to the DocTeam (what's left of it, anyway) so that someone with CVS access can commit it after an editorial once-over. -- John Weiss
Re: A couple of comments on the new docs
On Mon, Aug 27, 2001 at 02:22:36PM -0700, Mike Ressler wrote: > > > On Fri, Aug 24, 2001 at 10:33:36PM -0400, Larry Kollar wrote: > > > > > - The "put a (tm) after PostScript or we'll get sued" is also, shall > > >we say, shrill. Unless the team has been warned repeatedly, the worst > > > > I haven't toned the Postscript (tm) :-) stuff down yet. I agree it gets a > bit pendantic - maybe I'll poke around on the Web and find out what common > practice is. Things like The Gimp should have attracted Adobe's attention > by now ;-) so I'll see how they label Postscript. A reminder: "DocStyle" is for people who are: a) Eager to help with LyX, but whose only experience with software documenation is a manual for Windoze; OR b) Eager to get glory or think that, by helping with the docs, it will give them the right to dicate to the coders what feature to put in next. I dealt with both, it would seem, during my time as editor-in-chief. I ended up doing a lot of editing, and soemtimes complete rewrites. (Seems some people never learned how to follow simple instructions during kindergarten.) So, "DocStyle" tends towards the shrill, because the volunteers wouldn't bother to listen to my polite requests. Sad but true. However, since a single, initial genuflection to trademark holders suffices, we can do that instead. (Actually, I think the repeated (tm) stuff was done to thumb our collective noses at trademark; remember, in the mid-90's someone tried to trademark "Linux" out from underneath Linus Torvalds. Sometimes excessive use can be a form of sarcastic protest .) -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: styles
On Tue, Aug 14, 2001 at 12:35:58PM +1000, Zenaan Harkness wrote: > Just a minor issue, but perhaps worth noting as more people with a > windows (MS Word) background come to GNU/Linux and Lyx. > > The "Tutorial", in the "What is Lyx" chapter, harps on about how "in > other word processors" you enter font sizes, tabs, etc. [snip] > Perhaps most people are not familiar with 'styles' from, eg. Ms Word. I now have to suffer through M$ Word at work. One of the first things I did was create styles that made Word behave more like LyX. The second thing I did was create macros that would repair those styles after Word decided that it knew better than me and hosed my styles. Frankly, I find M$ Word's "styles" severely lacking. -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Proposed reorg
On Thu, Aug 02, 2001 at 10:39:50AM +0200, Jean-Marc Lasgouttes wrote: > >>>>> "Mike" == Mike Ressler <[EMAIL PROTECTED]> writes: > > Mike> "What's that thing?" "Well, it's a highly technical, sensitive > Mike> instrument we use in computer repair. Being a layman, you > Mike> probably can't grasp exactly what it does. We call it a > Mike> two-by-four." > > I have to admit I do not get this one. Probably knowing what a > two-by-four is would help :) A wooden beam with a cross-section of roughly 2"x4". It's the most common size wooden beam used in construction. The walls of all homes build in America during the last 50 years are framed using two-by-fours. At one point in time, two-by-fours used to have a cross-section of exactly 2"x4". For reasons that I forget, the actual size of a two-by-four is a bit less than 2" by a bit less than 4". Maybe it had something to do with making these wooden beams have nicer, rounder measures when converted to metric. Or, it may be that the lumber industry started making two-by-fours smaller to save on wood during some shortage or other, and the size change stuck. Either way, we still call them two-by-fours. You'll also find 2-by-2's, 2-by-6's, 4-by-4's (for heavier-duty posts), 1-by-8's, and 1-by-2's. These are the most common sized wooden beams used in construction in America these days. -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Proposed reorg
On Wed, Aug 01, 2001 at 09:00:35AM -0400, Amir Karger wrote: > > Aside from the cultural boundary of not knowing who Will Robinson is, lots > of people who use LyX don't know English all that well, so all they'll see > is the "DANGER, DANGER". Then add the fact that the docs often get > translated (Intro is in 10 languages now, by my count), and who knows what > the warnings will look like there? > > Yes, it's funny. No, it's not language/culture-portable. Whoops! I never thought of that, and I really should know better. Okay, pitch it. -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Proposed reorg
On Tue, Jul 24, 2001 at 03:11:06PM -0700, Mike Ressler wrote: > > 4) Remove Reference from the Help menu. Remove Reference completely. It was stillborn, really. > Philosophy: the Intro should be an intro: it is assumed to be chapter 1 > for all other docs. I would suggest that the very first line of the very first paragraph of the very first section of all of the docs refer the reader immediately back to the Intro, as they do now. Rewrite my stuff to suit your own sense of humor (and *do* be humorous!), but do keep the immediate backreference. If we're going to really make Intro the Chapter 1 of all of the docs, we'll have to make sure people know to read it first. Other than that, I look forward to seeing the result of your efforts! -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Proposed reorg
On Wed, Jul 25, 2001 at 10:36:36AM -0700, Mike Ressler wrote: > On Wed, 25 Jul 2001, John Levon wrote: > > > how about "mail [EMAIL PROTECTED] or see the lyx.org website" ? > > more accessible If you're going to move stuff out of Intro.lyx and into DocStyle.lyx, then "DocStyle.lyx" needs to live in a more prominent location. How about generating an HTML or PS version and putting it someplace on the LyX website? Then the documentation can just make reference to a URL and be done with it. -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Proposed reorg
On Wed, Jul 25, 2001 at 09:28:34AM -0700, Mike Ressler wrote: > > > Also ditch the "DANGER DANGER" thing. It is NOT a good thing to have as the Humorless lot Ducking behind sofa... -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Unreviewed dvi docs patch
On Mon, Jul 23, 2001 at 09:38:04AM -0700, Mike Ressler wrote: > > As a side note, I've noticed that diffs are a terrible way of trying to > see what is different in a LyX doc. The diff itself is impossible to read [snip] > into LyX :-) Perhaps we should do something "silly" like put all edits in > blue or underlined or something until the change is mutually agreed on or > some such. Any recommendations for dealing with this? This is where I come in handy. :) Mike, don't "Put things in blue or underline or someting like that," which will screw up the documentation style. Do what we all did in the days before wordprocessors that magically keep track of every change by every contributor, wax the kitchen floor, and brew you a cup of tea. Just send doc-snippets back and forth. This is exactly what I did during the First Great Rewrite days. First, never have more than one person working on the same part of the document at the same time. That means you'll be passing a lyx file with the morphing text back and forth between only two people: yourself and the contributor. If it's just a paragraph that's going into section 3.2.1, then just ship that paragraph back and forth. If, however, it's all of section 3.2.1, start the fragment *.lyx with this: 1. Placeholder section 1.1 Placeholder subsection 1.1.1 This way, if there's also a section 3.2.1.1 and 3.2.1.2 that your contributing author will be working on, you can preserve the WYSIWYM-look of the doc-fragment undergoing change. -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Updated Tutorial and UG
On Wed, Jul 18, 2001 at 08:35:28AM -0700, Mike Ressler wrote: > > I will work on it later today, and I'm hoping at least a few people > respond to my proofreading plea. Are you ready to release fix3? If so, > I'll scramble to get as much done as I can, then just declare it good > enough. I intend to look at them, but you may have to wait for a glaze firing (babysitting the kiln consumes a day). -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: LyX docs in russian
On Wed, Jun 20, 2001 at 10:51:15PM +0400, Vitaly Lipatov wrote: > On 19 June 2001 12:19, Jean-Marc Lasgouttes wrote: > > >>>>> "Mike" == <[EMAIL PROTECTED]> writes: > > > > Mike> your work would be greatly appreciated. However, don't start > > Mike> with DocStyle.lyx - that is more for the people who write > > Mike> documentation. Start with Intro.lyx and Tutorial.lyx; these are > > Mike> the documents new users read (or at least _should_ read) first. > Our group have to know some rules from DocStyle.lyx. This is goal for > translate it. > Absolutely, we start with Intro.lyx Vitaly, if you look at the "Translator's Guide", you'll see that your first task as Chief-Translator is to write a "Russian Supplement to the LyX Documentation Style Guide". now, I don't recall what I did with the Translation Guide, but I'm sure someone can help you out with that part. One thing to remember is that you DO NOT need to translate DocStyle.lyx: after all, your transation team has to know English if they're going to do any translating! :) No, the goal of the Russian DocStyle Supplement is to distill the elements of proper Russian writing style down to a few good reminders. In the end, your Supplement should reflect whatever the current acceptable writing style is at the big publishing houses in Mosow or Petersburg or wherever. Also, the resulting docs should be an "easy read". Look at the Translator's Guide for more pointers. -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: "Popups"
On Fri, Jun 08, 2001 at 09:53:51AM -0700, [EMAIL PROTECTED] wrote:
> On Sat, 2 Jun 2001, John Levon wrote:
> > Are the doc team still insistent on this term ? It seems both unfamiliar
> > to users, and a bad description (the dialogs do /not/ pop up).
>
> IIRC, this was chosen as a compromise - we wanted to avoid the developer
> jargon ("dialog box" was deemed jargon)
Yup, this was a bone of much, much contention way back when...
> and use something a typical user might say. What does M$ Word
> (shudder!) call such things? That, unfortunately, is what we should
> attempt to be consistent with, since that is what typical users will
> know.
I think M$ also uses the word "Dialog Box". Or used to; now
everything is a Wizard...
--
John Weiss
"Not through coercion. Not by force. But by compassion. By
affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Introduction in User Guide
On Thu, May 24, 2001 at 09:12:02PM -0400, Amir Karger wrote: > Hi. > > I don't have the energy to respond to each piece of the message. Basically, > though, it's a neat idea but I really don't know if it'll work in practice. [snip!] Okay, I like many of the ideas I see flying around here. I also like the motivation: Make it easy for the user to climb that learning curve. That was precisely my goal when I did the first LyXDoc rewrite. There was also some of your proposed parallelism between the Tutorial and the UG. There is, however, a degree of repetition of content between these two docs. That's one thing you'll need to be sure to avoid. While I'm talking about unnecessary repetition, this is exactly why "Intro" was born. I was copying and pasting the exact same opening chapter into all 6 docs, then having to make changes in 6 places everytime I needed to do maintenance. Naturally, one should avoid content repetition whenever possible. I do think that you may be able to pull off this parallelism, at least to some degree. I suggest that you start with an outline for each doc (new or existing) and propose this. We can then send it through a couple of rounds of peer review. If we can then use the new structure with only cut-n-paste and a minimal bit of rewrite (to keep the flow of the text smooth), then just go for it. If the new structure requires greater effort to implement, then we should think more carefully about what to do next at that point in time. -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Introduction in User Guide
to in the UG could probably be moved to Intro. Don't bother moving it. Let's drop the propaganda (a holdover from the Matthias Ettrich days, anyhow ;) ) and just have a paragraph or two "tooting our own horn", just to demonstrate to the M$ Word crowd what they gain from LyX. And, we can be magnanamous and state what you lose. > > Also, maybe look at adding an FAQ or Q&A type document. There are lots of > > similar questions asked on the LyX User's mailing list all the time. Herb > > Voss has invested (I suspect) a great deal of time in developing his web > > pages, but really, the user shouldn't have to go digging that far for many of > > the answers he has up there...they should be in the documentation. [snip!] > > Ahem, there is a much ignored FAQ in the documentation. It even points to > Herb's site. Given that Herb's site is so good, but focussed a bit more on > tips and tricks, I want the FAQ to cover the true FAQs, [snip!} I'm not on the lyx-users list anymore (too much traffic to keep up with), so I can't be too sure of what I'm about to say. At the time I was LyXDoc-Grand-Poobah, almost all of the FAQ that came through were questions of the form "How Do I...?" There *was*, indeed, once a document called "HowDoI.lyx". It was supposed to be the de-facto FAQ, organized like an FAQ, with the title "How Do I..." and chapters, sections, and subsections all having names beginning with "..." and ending with "?". The "HowDoI.lyx" would give a quick tip, if possible, and point the user to an appropriate document and chapter/section/subsection/etc. that explained all in greater detail. The rest of the documentation was *supposed* to dovetail with this FAQ. Didn't happen. No one bothered to fill in "HowDoI.lyx" beyond the 2 or 3 entries I put in there to start with. Alas, even if someone had, I doubt anyone would have made sure it dovetailed with the other docs. Last Topic: The "daunting" LyXDoc Style Sheet. Sorry boys, but this one has to be strident ... or, better put, as strict as a nun in a 50's era catholic school. There is no way around this. The Style Sheet grew out of my experiences as Editor. I'd have volunteers. They would write their contributions in a vacuum, ignoring the rest of the document. I would then spend enormous time fixing what they sent me --- to the point where I could've written the section myself from scratch with less effort. I would tell people that we'd use Typewriter-style for codes and SansSerif for keybindings and menus. Volunteers would come up with all sorts of weird contortions of logic to explain away why they totally ignored this standard. I'd find seven different forms of "remark-from-the-author" ... all seven in the same section from the same person. I'd find all sorts of creative use of font, underlining, italicizing, and boldfacing covering up totally uncreative content. I'd get contributions that had barely any organization or structure. I'd merge sections from different people together, and end up with a chapter that switched from British English to American English to formal speech to informal speech to obtuse speech willy-nilly! Worst of all, I had to tell volunteers that the effort they made needed fixing without invalidating their efforts, insulting them, and generally sending them storming off in a huff. It was a major tightrope act, and I fear that I wasn't too successful. This, gentlemen, is why the Style Sheet is so strict and emphatic. If you fail to specify *exactly* what the rules are, if you leave any wiggle-room, your volunteers will send you whatever they feel like, leaving you to either fix it or let the docs descend once more into chaos. So, beware of wasted effort trodding the path that I already walked. -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: double spaces at the end of a sentence: readability
On Wed, May 02, 2001 at 09:15:49AM +0200, Jean-Marc Lasgouttes wrote: > > On a more serious note, visual feedback on end-of-sentence spacing > would be nice, but probably a lot of work. _And_ it would not be > correct french typography, so we would have to adapt it to language. This, I believe, is why *all* of us decided not to do visual feedback for end-of-sentence-periods. Writing an algorithm that would get it right for every language and every type of period --- remember, there's abbreviation periods, too --- would be a headache-and-a-half. There were more pressing issues that needed work then, and there are likely more pressing issues that need it now. FYI: When I use LyX, I always type two spaces after an end-of-sentence-period, even though I know nothing will happen, and I can tell perfectly well where my sentence ends on my own, thank you very much. I do this double-tap on the space bar to maintain a habit. After all, I also use text editors, and sometimes have to use other work processors, where I'll need to add that extra space. -- John Weiss "Not through coercion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Key-binding documentation dilemma
On Thu, Nov 30, 2000 at 12:22:12PM -0800, Mike Ressler wrote: > Hi, > > I'm working on updating the keyboard shortcuts in the docs (starting with > the User Guide). Given that I'm former editor-in-chief of the LyX Documentation Effort and remain its floating spiritual guide, I think it's time I weigh in on this... 1. Different manuals will need different approaches. It's already been mentioned that the Tutorial should pretty much run with the default bindings, whatever they are. This makes sense; a user reading the Tutorial ain't gonna know or care how to change his keybindings. For the UG and EG, a) Prefer the default bindings; b) However, when deemed necessary, also document the other major binding(s) *in* *addition* *to* the default (either parenthetically or in footnotes; c) Finally, and above all else, do whatever is most appropriate for the flow of the text. This, preservation of readability, takes priority over all else. 2. Full documentation of all bindings belongs in the Reference Manual. Someone else noted that we should document the bindings with the functions, as we currently do. This is by design, folks. If necessary, we can reorganize the RM a bit, junk unused chapters, and move bindings to prominence. An appendix in the UG would, therefore, be redundant. Just refer to the Reference Manual. 3. The RefMan needs a new chapter, one listing keybindings. a) Each major section would be for a particular flavor: (i) Menus and Generic Defaults (ii) CUA-like Default Bindings (iii) Emacs-like Default Bindings b) Within each major section, bindings would be grouped by function/purpose. c) Each group of bindings would be listed by keystroke and sorted lexically. d) Each keybinding would refer to the appropriate reference entry in the chapter documenting lyxfunc's. If no such reference exists, add one. e) For the sake of the printed version, every section/subsection/whatever will make use of "muticols" and be put in at least two columns per page. (Online readers can always use the TOC-menu to navigate.) f) If appropriate, we'll put pagebreaks into this chapter so that users can print out "quick-reference" sheets for the group(s) of bindings they use the most. So say I! -- John Weiss "Not through coersion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Key-binding documentation dilemma
On Fri, Dec 01, 2000 at 01:39:05PM -0500, Amir Karger wrote: > On Fri, Dec 01, 2000 at 05:27:05PM +0900, Miyata Shigeru wrote: > > Why don't you write a perl script to parse users' lyxrc, preference, ui and > > bind files, and to update UserGuide.lyx? > > But then, each user would need a local copy of that file. (I guess you would > put it in /tmp?) Seems kind of complicated. It will also consume disk space. No... not a good idea. Plus, it excludes one set of default bindings (e.g. Emacs) in favor of another (e.g. CUA). We need to document *all* bindings, and the place for that is in the Reference Manual. More to come shortly... -- John Weiss "Not through coersion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: docs for 1.1.6: What strategy?
On Mon, Nov 20, 2000 at 02:38:10PM -0500, Amir Karger wrote: > On Mon, Nov 20, 2000 at 11:12:20AM -0800, [EMAIL PROTECTED] wrote: > > On Sat, 11 Nov 2000, R. Lahaye wrote: > > > > I would like to formally request that a new CVS branch be made for lyxdoc > > - probably with "lyxdoc" for the new documentation and "lyxdoc_1.1.5" for > > the 1.1.5 stuff, similar to the source code branches, and with the same > > user access as now. > > That sounds like a good branching. Better yet, why not have a single "lyxdoc" CVS branch and use tags to mark completed docs for a given LyX release? You *can* create tags other than for branches. You can also delete existing tags, permitting you to make those, "Ooops! Forgot to fix this," changes while still keeping a "1.1.5" tag. See the CVS manuals for more info. -- John Weiss "Not through coersion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: docs for 1.1.6: What strategy?
On Sat, Nov 11, 2000 at 05:31:13PM +0900, R. Lahaye wrote: > > Hi, > > I'm new to this 'doc' list. > > > I believe 1.1.6 will have a big impact on the docs. > So many things have changed (dialogs, menus, bug-fixes etc.). As I recently said in an earlier email, the proper way to get the LyX Docs synchronized is for the developers to start writing new entries for "Reference.lyx". Someone else can come along and edit them for correct English, as well as prune "dead" entries. The updated "Reference.lyx" can then serve as the information source for updating the other docs. > What sort of strategy will be followed with the upcoming 1.1.6 release ? None, I fear. > Will the updates be done AFTER the release ? Most likely, since the developers don't seem to want to or have time to add entries to "Reference.lyx" (which is really quite painless, BTW). > I suppose that the English docs go first, followed by the > translations, or does everthing go simultaneously ? No, the rule is that the English docs are updated first. Translation projects will then use the new English docs as the information source for updating their own versions. Why English? Well, everyone on this list appears to have a good grasp of it. Only a few of us can speak French or German or Danish, so that would limit the pool of DocTeam and Translation Project members. ;) -- John Weiss "Not through coersion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Intro.lyx in Hebrew
On Tue, Jul 25, 2000 at 03:33:15PM -0400, Amir Karger wrote: > On Tue, Jul 25, 2000 at 09:27:54PM +0300, Lior Silberman wrote: > > On Tue, 25 Jul 2000 [EMAIL PROTECTED] wrote: > > > > Although the DocStyle forbids, Hebrew style accepts the passive voice more > > than English. It might be acceptable do use "xyz should now be done" in > > addition to "you should now do xyz". Question #1: Did you read the DocStyle section for translators? I believe it says, someplace, something like... > If Hebrew style says the passive voice is good (of course it does; several > binyanim have nothing *but* passive voice!) then it's totally fine to use > it. English doesn't have binyanim (in the same way) so passive voice usually > sounds bad. At work, the tech-writers were discussing the merits and drawbacks of using the passive voice to sound more professional. In American English, during the past few decades, school teachers have been trying to get students to avoid the passive voice whenever possible. I'm guessing that, at one point, using the passive voice gave speech a certain air of authority or objectivity. It's been so overused, however, that there's now this trend (at least here in America's schools) to teach students to avoid it unless absolutely necessary. As I said in the section for translators, however, other languages have other rules. In some languages, there's a special verb tense that one *must* use whenever conveying information that's heresay (i.e. not your own direct experience). English has no such thing. English does have a gender-neutral pronoun, "one," that you use in place of "he" or "she". It sounds rather archaic to some, however, and most people use the plural "they" nowadays instead (though that's technically incorrect). I was unaware that Hebrew had implicit gender built into every sentence with "you" as the subject. Here's a suggestion: Assume that you're writing the document as if you were speaking to a friend, but that you must do so in a way that doesn't imply gender. If passive voice is how one does this in Hebrew, go for it. If plural works, use that instead. Use good judgement, whatever you decide. -- John Weiss "Not through coersion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Intro.lyx in Hebrew - Second draft and summary
On Mon, Jul 31, 2000 at 01:42:58AM -0200, [EMAIL PROTECTED] wrote: > > Sorry, but I do not agree, when in formal writing. I also somtimes use female > notation when writing informally (e.g. in email), but I wouldn't use > that in a book. You didn't read the DocStyle.lyx file, did you? Or, you didn't read it closely enough. One thing I stated in it is this: The LyX manuals are *NOT* formal documents. They LyX manuals, are, in fact, un-manuals. They are supposed to be informal. They are supposed to be friendly. They are supposed to be congenial. The only exception I permitted in the Style Sheet for Translations was this: be informal as long as it is casual. Do not be informal if it would be rude. In my english classes in grade school, I learned that one uses "he" even if one means "he-or-she". In the LyX manuals, I alternate between "he" and "she" from paragraph to paragraph. Do the same, insofar as it isn't rude. That's the *RULE*, as written in the Style Sheet for Translations. And read the Style Sheet for Translations again, please. From the two threads I've seen, it doesn't look like you read it closely enough. Crabbily Yours, -- John Weiss "Not through coersion. Not by force. But by compassion. By affection. And, a small fish." -His Holiness, the 14th Dalai Lama
Re: Installing tex classes (again)
On Thu, Nov 25, 1999 at 07:01:34PM +0100, Jean-Marc Lasgouttes wrote: > > I was about to add the section on TeX packages to Customization, when > it occured to me that I absolutely do not know _where_ I should put > it. Could a kind soul propose a reasonable place? The thing is that if > somebody wants to install foiltex he is probably not interested in the > format of the layout file... Well, I would suggest putting at the end of Customization, but before the "Printer Tutorial" chapter. Why? - TeX packages aren't *directly* related to LyX, but, like that old, dated printer tutorial, are indirectly related. So, they go at the end of the Customization doc. - The "Printer Tutorial" chapter should remain last. In fact, I'm strongly considering removing it and placing it into its own document. That, Jean-Marc, is my "official" word on where to put it. -- John Weiss
Re: Name of Extended Features manual
On Mon, Oct 25, 1999 at 09:33:52AM -0500, Mate Wierdl wrote: > >"ExtendedFeatures" is the abbreviated name, a mnemonic. Maybe if all >of you would READ the manual instead of just the title... > > John, we did read the manual. Our problem is that `extended features' > is not correct grammatically. You are not extending existing features > of lyx; in the manual you talk about some "more" or "additional" > features of lyx (that were not talked about in the Users' Guide). You've just made my point: you're taking a sufficiently vague mnemonic, which could be interpreted many, many ways, forcing a single interpretation on it, then playing Grammar Police. It's a mnemonic, an abbreviation. That's why, in the intro to the manual, I "talk about some 'more' or 'additional' features of lyx (that were not talked about in the Users' Guide)." I expand the abbreviation, explain the mnemonic. "Extended Features" is a compromise. It's short enough to fit on a menu, vague enough to hit close to the content, long enough to imply its subject, and precise enough to be interpretable at all. I could rename it, "Garbage Pail," which is another way to describe the EG's purpose. It's not terribly accurate, to say nothing of elegant. I could rename it, "LyX Extensions, Specialized and Advanced Features," which would never fit in a menu entry, and has no convenient, menu-length mnemonic that would please all of you Grammar Police and Nit-Pickers. Of course, I could rename it, "lugeagp," an abbreviation that cannot be misinterpreted because it's only has meaning to me, and even then, only until I go to bed, when I'll likely forget what it means. I think, however, that Unix has enough cryptic, arcane names floating around it. Besides which, "Extended Features" can be rewritten as "Features which are Extended," a phrase that means something TOTALLY different than, "extending features," which you claim it means. Your grammar is wrong. -- John Weiss
Re: Name of Extended Features manual
On Thu, Oct 14, 1999 at 11:47:36AM +0200, Jean-Marc Lasgouttes wrote: > >>>>> "Bruce" == Bruce Momjian <[EMAIL PROTECTED]> writes: > > Bruce> I am reading the Extended Features manual, and it is very good. > Bruce> However, I would like to suggest a different name for this > Bruce> manual. I think of Extended as Extending, or a manual about > Bruce> extending the features of LyX. Seems it should be called > Bruce> "Advanced Features." Auugh! N! We've been through this discussion already! After pulling my hair out for weeks trying desperately to come up with a name that all the devvies liked, I came up with "Extended Features." Please please please let's not reboil old cabbage. BTW: I looked at the docs recently. Extended Features is not at all in the format I outlined several years ago. Specifically, various sections have no indication of who the author is. I suggest, before going any further with this "debate", that y'all re-read the intro to EF and see what I had in mind with that doc... -- John Weiss
Re: Name of Extended Features manual: StopIt!
Stop it StopIt *StopIt* *STOP*IT* **STOP** **IT**!! ENOUGH WITH THE MANUAL NAMES, ALREADY! "Extended" is for extending and customizing LyX?! WHAT THE H*** ARE YOU PEOPLE THINKING?! WHY WOULD WE HAVE A "Customization" IF THAT WERE TRUE?! Okay... I'm trying to calm down... I'm trying to calm down... On Thu, Oct 14, 1999 at 11:51:07AM -0700, [EMAIL PROTECTED] wrote: > > We beat the naming issue to death about a year ago. I think "Extended" was > the compromise that caused the fewest vegetables to be thrown. AGREED! The names of the manuals are an ABBREVIATED SUMMARY OF CONTENT, not the end-all be-all. We went through this already, and settled on what we felt was the best choice. Since I began the whole doc-reorganization 4 years ago, and began the DocTeam, period, and laid out the current design of the new documents, what I hereby say is The Final Word: The documents are organized based on *reading* *order*, and nothing more. You need to read Intro before you can read any of the others. Some people need to read the Tutorial before moving on. Some don't. The User's Guide assumes you're read the first two, and covers the most-frequently used subset of LyX features. Extended is basically an extension of the UG. It contains less-frequently used features. Using EF impiles that you have read the UG. Customization and Reference are last in the sequence. >From time-to-time, things may migrate from EF to UG or vice versa, as we fine-tune the organization. But my description of the purpose of the manuals --- WHICH IS ALSO IN "Intro," if y'all had bothered to read it --- is sacrosanct and must never be violated! If y'all don't cut it out, I will go and rename the manuals to: Stage 1 Stage 2 Stage 3 Stage 4 Stage 5 Stage 6 ... thereby forcing you to read them, instead of just looking at the titles. (And if I start feeling *really* malicious, I'll give 'em names like "Eqiv L1," "Eqiv L2," "Eqiv L3," so that you'll *really* have to read them. ;) Your former Doc-Editor-In-Chief/Tyrrant, -- John Weiss
Re: Name of Extended Features manual
On Fri, Oct 15, 1999 at 10:19:47AM -0400, Bruce Momjian wrote: > > > >I think of Extended as Extending, or a manual about > >> Bruce> extending the features of LyX. > > > > Agreed. `Extended Features' does not seem grammatically correct: are "ExtendedFeatures" is the abbreviated name, a mnemonic. Maybe if all of you would READ the manual instead of just the title... > Maybe Special Features? Nope. That one got shot down *very* early in the debate. Nothing special about those features. > I think Advanced is ok because it is for advanced users. No, it's not. That's the whole reason why we changed it last time... -- John Weiss
Re: Name of Extended Features manual
On Thu, Oct 14, 1999 at 02:44:37PM -0500, Mate Wierdl wrote: > "Additional Features" Nixed even before Extended Features. > "Extra Features" Also nixed > "More Features" Don't like it. -- John Weiss
Re: Document versions.
On Tue, May 18, 1999 at 02:01:26AM +0200, Pierre-Henri Boinnard wrote: > > Hello, > > I think it would ease and clarify the translation work if a version > stamp is included in each document. > > What's your opinion ? Well, when I was head of the LyX Documentation Project wy back when, I intended that the latest, official version of the docs would have the same version as the rest of LyX. When we reached a point where the stable version of LyX froze, but we kept going with official doc-releases, we *could* tack on another number, e.g. 1.0.3.4 for the 4th version of the docs after v1.0.3 of LyX. During the Great Doc Rewrite of the v0.10.* series, I did incremental releases of the docs with a date attached: yymmdd. A word to all our translators: Stick with whatever's packaged in an *official* stable release when it comes to the LyX documentation. Don't try to keep up with the changes in the English version every pre-release. They'll settle down as of the official release. Additionally, if you're translating off of version i.j.k of LyX, don't automatically jump to i.j.k+1 --- finish whatever section you're translating first. It is unlikely that sections will heavily rearrange themselves without very loud prior warning, so this strategy is always a safe one. Once you've finished translating that section you're working on, *then* start working from ver. i.j.k+1, so that you have less cleanup work to do after the fact. Even then, remember that you should be translating the stablest docs *first*. Make life easy for yourself. -- John Weiss
