Introduction</> <para> blah-blah-blah This document describes version 1.0.53 of The GNOME Application </para> </sect1> -------------------------- 2. Documentation should contain names of authors of the application itself and the documentation, along with info for submitting bug reports. For small docs, the suggested way is to put it in a separate <sect1> at the very end of the document, e.g. <sect1 id="authors"> <title>Authors</> <para> GNOME Application was written by GNOME Hacker (<email>hacker@gnome.org</>). Please send all comments, suggestions, and bug reports to the <ulink type="http" url="http://bugs.gnome.org">GNOME bug tracking database</>. Instructions for submitting bug reports can be found on-line at <ulink type="http" url="http://bugs.gnome.org/Reporting.html"> http://bugs.gnome.org/Reporting.html</>. </para> <para> This manual was written by GDP Member (<email>you@your.address</>). Please send all comments and suggestions regarding the manual to the GNOME Documentation Project at <email>docs@gnome.org</>. </para> </sect1> ---------------------- 3. If you use any of the trademarks, you should add to <legalnotice> section appropriate legal junk, e.g. <legalnotice> <para> This document can be freely redistributed according to the terms of the GNU General Public License. </para> <para> Linux is a trademark of Linus Torvalds</para> <para> UNIX is a trademark of X/Open Group</para> <para> Macintosh is a trademark of Apple, Inc.</para> <para> All other trademarks are property of their owners</para> </legalnotice> ----------------- Do you agree with these? or do you think there are better ways? Let me know. Now, two more sensitive issues: A. Why many docs (in particular, users guide) contain sinister reference to "other operating systems"? Is there a taboo on saying "MS-Windows" or "Macintosh"? For me, it sounded childish. B. Should we include in guidelines a suggestion to use term GNU/Linux rather than Linux? Please do not consider it as a flamebait. We all know what RMS has to say on the matter. I am not asking for a discussion on whether he is right (I personally think he is) or whether it is not worth the inconvenience. I am just asking, whether this should be decided as a matter of GDP guidlines or should be left to individual authors. Best, Sasha From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 13671 invoked from network); 24 Jan 2000 16:43:34 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 24 Jan 2000 16:43:34 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA30227 for <gnome-doc-list@gnome.org>; Mon, 24 Jan 2000 11:43:31 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id QAA05571 for gnome-doc-list@gnome.org; Mon, 24 Jan 2000 16:43:08 GMT Date: Mon, 24 Jan 2000 16:43:08 +0000 From: Telsa Gwynne <hobbit@aloss.ukuu.org.uk> To: gnome-doc-list@gnome.org Subject: Re: documentation guidelines Message-ID: <20000124164308.A5514@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <200001241557.KAA07080@copiague.math.sunysb.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <200001241557.KAA07080@copiague.math.sunysb.edu> On Mon, Jan 24, 2000 at 10:57:56AM -0500 or thereabouts, Alexander Kirillov wrote: > Hi, guys, > here are some minor suggestions for "documentation guidelines" - if > everyone agrees, we'll add them to GDP -Howto (being written now). > ------------------------- > 1. Application documentation should say which version of the > application it documents Good plan. > 2. Documentation should contain names of authors of the application > itself and the documentation, along with info for submitting bug > reports. For small docs, the suggested way is to put it in a > separate <sect1> at the very end of the document, e.g. Don't many of the GNOME documents already have a by-line at the start, in all the bookheader/artheader stuff? But I agree: feedback addresses for programmer and documenter (if different) are good. > (<email>you@your.address</>). Please send all comments > and suggestions regarding the manual to the GNOME Documentation > Project at <email>docs@gnome.org</>. ... And that will solve the problem of what happens when people move on, change email addresses, suddenly recall they should be revising, not reading email, etc :) > ---------------------- > 3. If you use any of the trademarks, you should add to <legalnotice> > section appropriate legal junk, e.g. Can someone tell me how this works? I nicked the layout of the gtop docs from the gnome-terminal one, and this section below magically created the legal notice page although I had done nothing to make this happen. I'm still baffled by how this happens. Someone will have to find a nice list of trademarks and copyrights, then. There's some amazing ones out there. If anyone has access to "In Search of Clusters" by Gregory Pfister, they will be enlightened and entertained by his list of trademarks with his annotations mixed in. "Ethernet is a trademark of Xerox Corp. (I never knew that!)" and so on :) > <legalnotice> > <para> > This document can be freely redistributed according to the > terms of the GNU > General Public License. > </para> > <para> Linux is a trademark of Linus Torvalds</para> > <para> UNIX is a trademark of X/Open Group</para> > <para> Macintosh is a trademark of Apple, Inc.</para> > <para> All other trademarks are property of their owners</para> > </legalnotice> So how's this work to generate the extra page? > Now, two more sensitive issues: > > A. Why many docs (in particular, users guide) contain sinister > reference to "other operating systems"? Is there a taboo on saying > "MS-Windows" or "Macintosh"? For me, it sounded childish. I hadn't noticed this until you pointed it out, but I agree. It makes sense sometimes, but there are occasions when people use it unnecessarily. I know nothing about Windows, but I do have a vague idea what the Next interface was like (I use windowmaker :)). Other people know about what Mac interfaces are like. Putting "other OSs" is not always very clear, whereas a specific reference to the other in question can help someone think, "Oh, that thing" or "Never seen that OS, so I don't need to worry what this was called there." > B. Should we include in guidelines a suggestion to use term GNU/Linux > rather than Linux? Interesting question. I take the point about GNU/Linux, but then we get into the issue of, if the point is to highlight the GNU-based origin of many of the apps and utilities, how to refer to systems where it's a commercial UNIX but it has a bunch of GNU tools on it: a situation that may arise if you have got the GNU tools to compile and install GNOME on Solaris or IRIX. As I understand it, if you're following RMS's reasoning, then you should refer to those as GNU/whatever, too, to indicate that the userland stuff is GNU packages? Perhaps this should be left to individual authors of the programs involved, and for general non-program-specific documentation be left to the writer? The GNU aspect isn't going to be left out: it's the G in GNOME, after all :) I don't know whether this is the right place or not: Dave told me after looking at some of my stuff that there are conventions to do with using DocBook which were not something I had picked up from the book (and I still maintain that, by the book, they're wrong, but hey :)). Perhaps putting those, and any more that crop up, into GDP guidelines would be worth it? The two I have run afould of so far are: o "Even if it looks and acts like a button, if it's not "technically" a button (and a definition would be good here, please), then mark it up as a <guilabel> rather than a <guibutton>" o Don't put things like <guimenuitem> and stuff inside <term> because it gets marked up funny by the Gnome-specific stylesheets. (and I still think the fix is to alter the stylesheet: the book says it's allowed :)) Telsa From ke@gnu.franken.de Thu May 11 23:31:00 2000 Received: (qmail 28373 invoked from network); 25 Jan 2000 06:48:31 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 06:48:31 -0000 Received: from rachael.franken.de (rachael.franken.de [193.175.24.38]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id BAA21784 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 01:48:30 -0500 Received: by rachael.franken.de via sendmail with stdio id <m12Czm8-0027WaC@rachael.franken.de> for gnome-doc-list@gnome.org; Tue, 25 Jan 2000 07:48:28 +0100 (MET) (Smail-3.2 1996-Jul-4 #4 built DST-Sep-8) Received: from chico.franken.de(193.175.24.33) via SMTP by rachael.franken.de, id smtpdAAAa09969; Tue Jan 25 07:47:53 2000 Received: by chico.franken.de with UUCP for gnome-doc-list@gnome.org id m12Czla-005CVcC; Tue, 25 Jan 2000 07:47:54 +0100 (MET) Received: by tux.gnu.franken.de (Postfix, from userid 270) id 1282CDC2A8; Tue, 25 Jan 2000 07:45:35 +0100 (CET) Sender: ke@gnu.franken.de To: Alexander Kirillov <kirillov@math.sunysb.edu> Cc: gnome-doc-list@gnome.org Subject: Re: documentation guidelines References: <200001241557.KAA07080@copiague.math.sunysb.edu> From: Karl EICHWALDER <ke@gnu.franken.de> Date: 25 Jan 2000 07:45:34 +0100 In-Reply-To: Alexander Kirillov's message of "Mon, 24 Jan 2000 10:57:56 -0500" Message-ID: <shemb6sl81.fsf@tux.gnu.franken.de> Lines: 70 User-Agent: Gnus/5.0803 (Gnus v5.8.3) Emacs/20.5 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Alexander Kirillov <kirillov@math.sunysb.edu> writes: | 1. Application documentation should say which version of the | application it documents, e.g. | | <sect1 id="intro"> | <title>Introduction</> | <para> | blah-blah-blah | This document describes version 1.0.53 of The GNOME Application | </para> | </sect1> This is useful info. I'd recommend to store this info as an attribute; maybe, in addition to your human readable text. | -------------------------- | 2. Documentation should contain names of authors of the application | itself and the documentation, along with info for submitting bug | reports. For small docs, the suggested way is to put it in a | separate <sect1> at the very end of the document, e.g. Also useful. Please, consider to use entities: <!DOCTYPE book [ <!ENTITY app-authors "GNOME Hacker1 (<email/hacker1@gnome.org/), GNOME Hacker2 (<email/hacker2@gnome.org/), and GNOME Hacker3 (<email/hacker3@gnome.org/)"> ]> ... <title>Authors</> <para> GNOME Application was written by &app-author;. ... | ---------------------- | 3. If you use any of the trademarks, you should add to <legalnotice> | section appropriate legal junk, e.g. Unfortunately needed... Please, think about an external file (entity) to be include by all manuals: <!DOCTYPE book [ <!ENTITY gnome-tm-list SYSTEM "gnome-tm-list.sgml"> ]> ... &gnome-tm-list; ... where gnome-tm-list.sgml contains <legalnotice>...</legalnotice>; if more appropriate, instead of SYSTEM you can use PUBLIC and resolve the entity via a catlog entry. Once you'll start to use private entities, think careful about namespace problems. | A. Why many docs (in particular, users guide) contain sinister | reference to "other operating systems"? Is there a taboo on saying | "MS-Windows" or "Macintosh"? For me, it sounded childish. That's an rhetoric issue -- the game we all play. Maybe, it has something to do with "damnatio memoriae". -- work: ke@suse.de | : http://www.suse.de/~ke/ | ------ ,__o home: ke@gnu.franken.de | ------ _-\_<, : http://www.franken.de/users/gnu/ke/ | ------ (*)/'(*) From d-mueth@uchicago.edu Thu May 11 23:31:00 2000 Received: (qmail 8393 invoked from network); 25 Jan 2000 16:19:48 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 16:19:48 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA17240 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 11:19:48 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id KAA00492 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 10:19:47 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Tue, 25 Jan 2000 10:19:47 -0600 (CST) From: Dan Mueth <d-mueth@uchicago.edu> X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org Subject: Documentation templates and references Message-ID: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Does the GDP have documentation templates for the various types of docs that accompany an application? After reading sasha's suggestions and questions, it seems like having all the GDP authors start with the same template (which gives examples of these various standards decided on by the GDP) would be a very good idea. This would help authors get started and would help maintain uniform documentation for GNOME applications. If these templates already exist, where are they? We could just say that the documentation for application X is good and can be used as a template, but I don't think this would give us the flexibility to provide a short, yet complete template illustrating all the various markup tags and nomenclature (eg: GNOME, not Gnome) GDP authors should use. Perhaps we should have (1) a simple template with just the basic tags which people use most, and then (2) a more complete GDP reference document which lists the proper markups, nomenclature, etc. Dan (muet) From kirillov@math.sunysb.edu Thu May 11 23:31:00 2000 Received: (qmail 3586 invoked from network); 25 Jan 2000 17:17:10 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 17:17:10 -0000 Received: from peconic.math.sunysb.edu (mail.math.sunysb.edu [129.49.18.67]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA21703 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 12:17:10 -0500 Received: from copiague.math.sunysb.edu (IDENT:root@copiague [129.49.18.192]) by peconic.math.sunysb.edu (8.9.3/8.9.3) with ESMTP id MAA15975 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 12:17:09 -0500 (EST) Received: (from kirillov@localhost) by copiague.math.sunysb.edu (8.9.3/8.9.3) id MAA10329 for gnome-doc-list@gnome.org; Tue, 25 Jan 2000 12:17:09 -0500 Date: Tue, 25 Jan 2000 12:17:09 -0500 From: Alexander Kirillov <kirillov@math.sunysb.edu> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000125121709.D10290@math.sunysb.edu> References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu>; from d-mueth@uchicago.edu on Tue, Jan 25, 2000 at 10:19:47AM -0600 As far as I know, no templates exist at the moment. I could write one - after we agree how it should look like, for example, which external entities we are going to use (see Karl's e-mail). Sasha On Tue, Jan 25, 2000 at 10:19:47AM -0600, Dan Mueth wrote: > > Does the GDP have documentation templates for the various types of docs > that accompany an application? After reading sasha's suggestions and > questions, it seems like having all the GDP authors start with the same > template (which gives examples of these various standards decided on by > the GDP) would be a very good idea. This would help authors get started > and would help maintain uniform documentation for GNOME applications. > >.... > Perhaps we should have (1) a simple template with just the basic tags > which people use most, and then (2) a more complete GDP reference document > which lists the proper markups, nomenclature, etc. > > Dan (muet) > > From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 18063 invoked from network); 25 Jan 2000 19:03:30 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 19:03:30 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA29397 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 14:03:27 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id TAA14366 for gnome-doc-list@gnome.org; Tue, 25 Jan 2000 19:03:04 GMT Date: Tue, 25 Jan 2000 19:03:04 +0000 From: Telsa Gwynne <hobbit@aloss.ukuu.org.uk> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000125190304.I12228@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote: > > Does the GDP have documentation templates for the various types of docs > that accompany an application? After reading sasha's suggestions and No. Dave (? -- someone, anyway :)) and I were talking about this on the docs channel the other day. I had been admiring the FreeBSD's folks' templates and thinking that the only way I ever got started with DocBook was to take someone else's (at least I had the sense to start with a GNOME one to get the same format!) and just mangle it. I made myself my own little template for future reference and was contemplating bulking it out and seeing whether it was any use to anyone. > We could just say that the documentation for application X is good and can > be used as a template, but I don't think this would give us the > flexibility to provide a short, yet complete template illustrating all the > various markup tags and nomenclature (eg: GNOME, not Gnome) GDP authors > should use. > > Perhaps we should have (1) a simple template with just the basic tags > which people use most, and then (2) a more complete GDP reference document > which lists the proper markups, nomenclature, etc. Sasha volunteered before me. I nominate him to do it :) (Also, I think he knows more about DocBook. :) Like exciting things like entities and stuff. And I keep finding more tags I could have used, too, and having to go back and add them.) What I thought would be handy is a sample article and a sample book chapter, with the correct GNOME DTD wotsit at the top, and the boilerplate at the start about authors, and then separate sections on "Different sorts of lists and when to use them. All the words and concepts you _could_ mark up _with_ _examples_" and so on. The DocBook book is great for definitions, but I find it poor on examples of "you have this word and concept and there are two tags that might apply. Which is the one to use?" Telsa From gleblanc@mail.redhat.com Thu May 11 23:31:00 2000 Received: (qmail 285 invoked from network); 25 Jan 2000 19:27:31 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 19:27:31 -0000 Received: from email.cu-portland.edu (email.cu-portland.edu [204.202.196.11]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA30815 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 14:27:30 -0500 Received: from cu-portland.edu (10.64.5.2 [10.64.5.2]) by email.cu-portland.edu with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2650.10) id CDTB5DY3; Tue, 25 Jan 2000 11:27:28 -0800 Sender: gleblanc@mail.redhat.com Message-ID: <388DF95D.965CD4FA@cu-portland.edu> Date: Tue, 25 Jan 2000 11:28:29 -0800 From: Gregory Leblanc <gleblanc@cu-portland.edu> X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.14 i686) X-Accept-Language: en MIME-Version: 1.0 To: Telsa Gwynne <hobbit@aloss.ukuu.org.uk>, gnome-doc-list@gnome.org Subject: Re: Documentation templates and references References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000125190304.I12228@aloss.ukuu.org.uk> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Telsa Gwynne wrote: > > On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote: > > > > Does the GDP have documentation templates for the various types of docs > > that accompany an application? After reading sasha's suggestions and > > No. Dave (? -- someone, anyway :)) and I were talking about this on > the docs channel the other day. I had been admiring the FreeBSD's > folks' templates and thinking that the only way I ever got started > with DocBook was to take someone else's (at least I had the sense > to start with a GNOME one to get the same format!) and just mangle > it. I made myself my own little template for future reference and > was contemplating bulking it out and seeing whether it was any use > to anyone. I haven't looked around the FreeBSD site, but I'll do that later. Do they have anything to go along with the templates, or are they just templates? I'm thinking like some documents that outlike the conventions and proper language style things, although these could be the "content" of the templates, I suppose. I for one would like to take a look at what you've got for purely self-serving reasons. > > > We could just say that the documentation for application X is good and can > > be used as a template, but I don't think this would give us the > > flexibility to provide a short, yet complete template illustrating all the > > various markup tags and nomenclature (eg: GNOME, not Gnome) GDP authors > > should use. > > > > Perhaps we should have (1) a simple template with just the basic tags > > which people use most, and then (2) a more complete GDP reference document > > which lists the proper markups, nomenclature, etc. > > Sasha volunteered before me. I nominate him to do it :) (Also, I think > he knows more about DocBook. :) Like exciting things like entities > and stuff. And I keep finding more tags I could have used, too, and > having to go back and add them.) Everybody seems to have this idea for the doc projects, but I haven't seen anybody write one yet. I've tried a couple of times, but I don't seem to have a good enough knowledge of DocBook to do the technical side, and I'm not clear enough on the best documentation conventions to create that part of it. If Sasha will volunteer, so much the better! :) > > What I thought would be handy is a sample article and a sample > book chapter, with the correct GNOME DTD wotsit at the top, and the > boilerplate at the start about authors, and then separate sections > on "Different sorts of lists and when to use them. All the words > and concepts you _could_ mark up _with_ _examples_" and so on. > The DocBook book is great for definitions, but I find it poor on > examples of "you have this word and concept and there are two tags > that might apply. Which is the one to use?" I think that's technically an "identifier", but whatever. Well, if it's not inline markup, use both? I'm not too clear on when I should use certain tags either, but I'm sure that Norm has a pretty good idea. :) If we give plenty of examples, and if all of the GDP docs are "model docs" within reason, then there should be plenty for people to work from. Greg From d-mueth@uchicago.edu Thu May 11 23:31:00 2000 Received: (qmail 21599 invoked from network); 25 Jan 2000 19:59:34 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 19:59:34 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA00993 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 14:59:34 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id NAA02207 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 13:59:33 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Tue, 25 Jan 2000 13:59:33 -0600 (CST) From: Dan Mueth <d-mueth@uchicago.edu> X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references In-Reply-To: <20000125121709.D10290@math.sunysb.edu> Message-ID: <Pine.LNX.4.10.10001251352290.2107-100000@enlightenment.uchicago.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII > As far as I know, no templates exist at the moment. I could write one > - after we agree how it should look like, for example, which external > entities we are going to use (see Karl's e-mail). > > Sasha Thanks for volunteering Sasha. I have added an entry called "GDP Document Template(s) and Reference Document" into the "General Docs" section of the GDP Documentation Status Table: http://www.gnome.org/gdp/doctable/doctable_list.php3?CategoryID=4 I added you (Sasha) as the primary author for this. When this mailing list thread has died out, anybody can make suggestions using the "Comments" facility of the doctable. Dan From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 19415 invoked from network); 26 Jan 2000 14:58:45 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 14:58:45 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id JAA19447 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 09:58:37 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id OAA14557 for gnome-doc-list@gnome.org; Wed, 26 Jan 2000 14:58:09 GMT Date: Wed, 26 Jan 2000 14:58:09 +0000 From: Telsa Gwynne <hobbit@aloss.ukuu.org.uk> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000126145809.A14195@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote: > If these templates already exist, where are they? ... > Perhaps we should have (1) a simple template with just the basic tags > which people use most, and then (2) a more complete GDP reference document > which lists the proper markups, nomenclature, etc. If these templates come to pass, may I make a small suggestion? I realise that people on virtual consoles or people who limit their windows to 25 lines from top to bottom will hate me for this, but hear me out. Please can we suggest that (a) Ending tags with </> is a bad idea unless it's clearly obvious exactly what it refers to at first glance. Really clearly obvious. (b) Lines should try to avoid being more than eighty characters long before a carriage return. (c) Use lots of whitespace. I was trying to compile the tarball of Balsa today. Not CVS or anything, just the "./configure; make; make install" one. It finally barfed for obscure reasons, but an initial problem I hit was that db2html produced over 200 errors and gave up, aborting the make. I had a poke at the balsa.sgml file to see what had happened. For some reason, db2html didn't like this at the top: <!doctype article PUBLIC "-//Davenport//DTD DocBook V3.1//EN" []> Does anyone see any problems that are obvious there? Is it case- sensitive or something? I was confused. In the end, I altered the "Davenport" to "OASIS" and it removed 95% of the errors. In a fit of enthusiasm I decided to remove the rest of the errors. The usual "this tag shouldn't be here, this tag doesn't have a start tag, you can't have a sect2 starting here" stuff was there. And when I looked, parts of it looked like this: <varlistentry><term>Check Mail Automatically Every...</><listitem><para>If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. <note><para>Using "0" as an interval is a <emphasis>really</> bad idea.</></></></></> </> </> One of those </>s was superfluous and removing that, and putting a </sect2>, elsewhere fixed a lot of it. But it took -ages-! I found it extremely hard to work out which </> referred to which tag. I ended up having to fill in almost all the end-tags and reformat it to use about three times the screen space to know where I was -- but I really think it was more legible. Is this something I just have to get used to, or what? It put me right off using </> for anything, because it gave me a headache trying to work backwards through seven endtags on the trot. But that's why I suggest that too many </> tags are bad! They're hard for new folk, at the very least. It's like counting brackets or something. I suppose I should note that it did at least have documentation, mind you :) And if I could get it to compile, I'd likely be glad about having the documentation to read! Telsa From gleblanc@mail2.aracnet.com Thu May 11 23:31:00 2000 Received: (qmail 23349 invoked from network); 26 Jan 2000 15:47:47 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 15:47:47 -0000 Received: from mail2.aracnet.com (root@mail2.aracnet.com [216.99.193.35]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id KAA22594 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 10:47:46 -0500 Received: from cu-portland.edu (216-99-218-48.dsl.aracnet.com [216.99.218.48]) by mail2.aracnet.com (8.9.3/8.9.3) with ESMTP id HAA32586; Wed, 26 Jan 2000 07:47:29 -0800 Sender: gleblanc@mail2.aracnet.com Message-ID: <388F1712.79762342@cu-portland.edu> Date: Wed, 26 Jan 2000 07:47:30 -0800 From: Gregory Leblanc <gleblanc@cu-portland.edu> X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.14 i586) X-Accept-Language: en MIME-Version: 1.0 To: Telsa Gwynne <hobbit@aloss.ukuu.org.uk>, gnome-doc-list@gnome.org Subject: Re: Documentation templates and references References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Telsa Gwynne wrote: > > On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote: > > If these templates already exist, where are they? > ... > > Perhaps we should have (1) a simple template with just the basic tags > > which people use most, and then (2) a more complete GDP reference document > > which lists the proper markups, nomenclature, etc. > > If these templates come to pass, may I make a small suggestion? > I realise that people on virtual consoles or people who limit their > windows to 25 lines from top to bottom will hate me for this, but > hear me out. > > Please can we suggest that > (a) Ending tags with </> is a bad idea unless it's clearly > obvious exactly what it refers to at first glance. Really clearly > obvious. > (b) Lines should try to avoid being more than eighty characters > long before a carriage return. > (c) Use lots of whitespace. Coming from doing a lot of programming on an Apple IIc, I do these by default, and I have to agree that they're generally good practices. I don't ever use tag minimization, it doesn't save much work, and it makes things impossibly hard to read. > > I was trying to compile the tarball of Balsa today. Not CVS or anything, > just the "./configure; make; make install" one. It finally barfed for > obscure reasons, but an initial problem I hit was that db2html > produced over 200 errors and gave up, aborting the make. I had a > poke at the balsa.sgml file to see what had happened. For some > reason, db2html didn't like this at the top: > > <!doctype article PUBLIC "-//Davenport//DTD DocBook V3.1//EN" []> > > Does anyone see any problems that are obvious there? Well, other than it being an invalid identifier, no. I'm pretty sure that Davenport never had anything to do with 3.1, they moved DocBook to Oasis much eariler than that. > Is it case- > sensitive or something? I was confused. In the end, I altered the > "Davenport" to "OASIS" and it removed 95% of the errors. I'm surprised that it did anything at all with that identifier in there. You might take a peek at your catalog files to see what DTDs you have on your system, so that you know immediately from looking at a source SGML file whether or not you can do anything with it. > In a fit > of enthusiasm I decided to remove the rest of the errors. The usual > "this tag shouldn't be here, this tag doesn't have a start tag, you > can't have a sect2 starting here" stuff was there. And when I looked, > parts of it looked like this: > > <varlistentry><term>Check Mail Automatically > Every...</><listitem><para>If selected, Balsa will connect > to your POP3 servers at the given interval and check for mail. > <note><para>Using "0" as > an interval is a <emphasis>really</> bad idea.</></></></></> > </> > </> Putting multiple </> tags together is a REALLY bad practice, how is one supposed to know what they appply to? A general rule for tag minimization (if you use it at all) is use it ONLY for short inline elements, not for things like <section>. > > One of those </>s was superfluous and removing that, and putting > a </sect2>, elsewhere fixed a lot of it. But it took -ages-! I found > it extremely hard to work out which </> referred to which tag. I > ended up having to fill in almost all the end-tags and reformat it > to use about three times the screen space to know where I was -- but > I really think it was more legible. > > Is this something I just have to get used to, or what? It put me > right off using </> for anything, because it gave me a headache > trying to work backwards through seven endtags on the trot. > > But that's why I suggest that too many </> tags are bad! They're > hard for new folk, at the very least. It's like counting brackets > or something. After both of us ranting, we have one small section of the templates/authors guide written! Thanks Telsa! Depending on how busy I get today, I can try to write up two or three paragraphs on tag minimization. I'll take some of the material here, reference this archived message, and some borrow some more material from what Norm has to say about this in his book. > > I suppose I should note that it did at least have documentation, > mind you :) And if I could get it to compile, I'd likely be glad > about having the documentation to read! After compiling it a couple of months ago, I'm waiting on Evolution. Go Gnome-mailer! Documentation is good, but only if you can read it. Perhaps the SGML source just hasn't been updated in a while (although that means that the content probably hasn't been updated either). Greg From joakim@styx.net Thu May 11 23:31:00 2000 Received: (qmail 12699 invoked from network); 26 Jan 2000 16:45:34 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 16:45:34 -0000 Received: from relay1.mail.styx.net (nocto.styx.net [148.245.18.42]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA27125 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 11:45:33 -0500 Received: from login1.styx.net (login1.styx.net [148.245.18.30]) by relay1.mail.styx.net (Postfix) with ESMTP id F10F53100B for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 10:45:31 -0600 (CST) Received: by login1.styx.net (Postfix, from userid 5004) id 82AEF6C035; Wed, 26 Jan 2000 10:45:31 -0600 (CST) Date: Wed, 26 Jan 2000 10:45:31 -0600 From: Joakim Ziegler <joakim@styx.net> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000126104531.E1713@styx.net> References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <20000126145809.A14195@aloss.ukuu.org.uk>; from hobbit@aloss.ukuu.org.uk on Wed, Jan 26, 2000 at 02:58:09PM +0000 On Wed, Jan 26, 2000 at 02:58:09PM +0000, Telsa Gwynne wrote: > Please can we suggest that > (a) Ending tags with </> is a bad idea unless it's clearly > obvious exactly what it refers to at first glance. Really clearly > obvious. Actually, you should try to avoid them altogether. The Davenport Group is going to move DocBook to XML sooner or later, probably sooner, as a beta DTD already exists, and XML doesn't support </>. In fact, if you avoid this and a couple of other SGML-specific constructs, you'll be able to port the SGML documents to XML without any changes (except the header) when that day comes. -- Joakim Ziegler - styx research director - joakim@styx.net FIX sysop - FIXmud admin - FIDEL & Conglomerate developer From sbaker@debian.org Thu May 11 23:31:00 2000 Received: (qmail 11668 invoked by uid 504); 26 Jan 2000 17:56:20 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 11665 invoked from network); 26 Jan 2000 17:56:20 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 17:56:20 -0000 Received: from master.debian.org (qmailr@master.debian.org [209.41.108.5]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id MAA32489 for <docs@gnome.org>; Wed, 26 Jan 2000 12:56:19 -0500 Received: (qmail 31059 invoked by uid 1368); 26 Jan 2000 17:56:05 -0000 Date: Wed, 26 Jan 2000 11:56:05 -0600 From: Steven Baker <sbaker@debian.org> To: docs@gnome.org Subject: remove from list Message-ID: <20000126115605.A30414@debian.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii User-Agent: Mutt/1.0i Hi there, Was wondering if you'd remove me from the list of Documentation people on the GNOME pages. I have no time to answer email right now, and haven't got reliable internet access. Perhaps inthe future, I'll try to help out. Tia, -Steven From ke@suse.de Thu May 11 23:31:00 2000 Received: (qmail 23542 invoked from network); 26 Jan 2000 18:26:16 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 18:26:15 -0000 Received: from Cantor.suse.de (Cantor.suse.de [194.112.123.193]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA02136 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:26:15 -0500 Received: from Hermes.suse.de (Hermes.suse.de [194.112.123.136]) by Cantor.suse.de (Postfix) with ESMTP id 2ACA81E1CC; Wed, 26 Jan 2000 19:25:44 +0100 (MET) Received: from Wotan.suse.de (Wotan.suse.de [10.10.0.1]) by Hermes.suse.de (Postfix) with ESMTP id A5DC410A034; Wed, 26 Jan 2000 19:25:39 +0100 (MET) Received: from Frechet.suse.de (Frechet.suse.de [10.10.0.123]) by Wotan.suse.de (Postfix) with ESMTP id F058E7F87; Wed, 26 Jan 2000 19:25:15 +0100 (MET) Received: (from ke@localhost) by Frechet.suse.de (8.9.3/8.9.3/SuSE Linux 8.9.3-0.1) id TAA17199; Wed, 26 Jan 2000 19:25:34 +0100 X-Authentication-Warning: Frechet.suse.de: ke set sender to ke@suse.de using -f Sender: ke@suse.de To: Joakim Ziegler <joakim@styx.net> Cc: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> <20000126104531.E1713@styx.net> From: Karl Eichwalder <ke@suse.de> Date: 26 Jan 2000 19:25:33 +0100 In-Reply-To: Joakim Ziegler's message of "Wed, 26 Jan 2000 10:45:31 -0600" Message-ID: <shu2k0adwh.fsf@Frechet.suse.de> Lines: 19 User-Agent: Gnus/5.0804 (Gnus v5.8.4) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Joakim Ziegler <joakim@styx.net> writes: | In fact, if you avoid this and a couple of other SGML-specific | constructs, you'll be able to port the SGML documents to XML without | any changes (except the header) when that day comes. . You'll have to change empty element tags nevertheless. . It will be easy to "convert" SGML documents to XML. . There will be no need to convert SGML documents; they will stay valid forever :) If a writer feels comfortable using SGML minimizations, he should be allowed to use these features. -- work : ke@suse.de Karl Eichwalder home : ke@gnu.franken.de From ke@suse.de Thu May 11 23:31:00 2000 Received: (qmail 30439 invoked from network); 26 Jan 2000 18:28:44 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 18:28:44 -0000 Received: from Cantor.suse.de (Cantor.suse.de [194.112.123.193]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA02372 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:28:43 -0500 Received: from Hermes.suse.de (Hermes.suse.de [194.112.123.136]) by Cantor.suse.de (Postfix) with ESMTP id 0B2D91E1D1; Wed, 26 Jan 2000 19:28:13 +0100 (MET) Received: from Wotan.suse.de (Wotan.suse.de [10.10.0.1]) by Hermes.suse.de (Postfix) with ESMTP id 2555F10A02F; Wed, 26 Jan 2000 19:28:12 +0100 (MET) Received: from Frechet.suse.de (Frechet.suse.de [10.10.0.123]) by Wotan.suse.de (Postfix) with ESMTP id AEF4E7F87; Wed, 26 Jan 2000 19:27:48 +0100 (MET) Received: (from ke@localhost) by Frechet.suse.de (8.9.3/8.9.3/SuSE Linux 8.9.3-0.1) id TAA17218; Wed, 26 Jan 2000 19:28:11 +0100 X-Authentication-Warning: Frechet.suse.de: ke set sender to ke@suse.de using -f Sender: ke@suse.de To: Telsa Gwynne <hobbit@aloss.ukuu.org.uk> Cc: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> From: Karl Eichwalder <ke@suse.de> Date: 26 Jan 2000 19:28:11 +0100 In-Reply-To: Telsa Gwynne's message of "Wed, 26 Jan 2000 14:58:09 +0000" Message-ID: <shpuuoads4.fsf@Frechet.suse.de> Lines: 11 User-Agent: Gnus/5.0804 (Gnus v5.8.4) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Telsa Gwynne <hobbit@aloss.ukuu.org.uk> writes: | One of those </>s was superfluous and removing that, and putting | a </sect2>, elsewhere fixed a lot of it. But it took -ages-! You should have tried `sgmlnorm' first ;-) which come with the jade package. -- work : ke@suse.de Karl Eichwalder home : ke@gnu.franken.de From d-mueth@uchicago.edu Thu May 11 23:31:00 2000 Received: (qmail 29908 invoked from network); 26 Jan 2000 18:50:56 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 18:50:56 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA04191 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:50:55 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id MAA08970; Wed, 26 Jan 2000 12:50:54 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Wed, 26 Jan 2000 12:50:54 -0600 (CST) From: Dan Mueth <d-mueth@uchicago.edu> X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org cc: Steven Baker <sbaker@debian.org> Subject: Re: remove from list In-Reply-To: <20000126115605.A30414@debian.org> Message-ID: <Pine.LNX.4.10.10001261246490.8814-100000@enlightenment.uchicago.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII > Hi there, > Was wondering if you'd remove me from the list of Documentation > people on the GNOME pages. I have no time to answer email right now, > and haven't got reliable internet access. Perhaps inthe future, I'll > try to help out. Steven, I removed you from www.gnome.org/gdp. Do you have a draft of the GNOME Installation/Configuration Guide that somebody else should get from you and continue work on? Dan From godoy@conectiva.com.br Thu May 11 23:31:00 2000 Received: (qmail 5892 invoked from network); 26 Jan 2000 18:53:55 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 18:53:55 -0000 Received: from animaniacs.conectiva.com.br (animaniacs.conectiva.com.br [200.250.58.146]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA04381 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:53:49 -0500 Received: from nexus.conectiva (IDENT:postfix@nexus.conectiva [192.168.255.17]) by animaniacs.conectiva.com.br (8.9.3/8.9.3) with ESMTP id QAA08515; Wed, 26 Jan 2000 16:52:55 -0200 Received: by nexus.conectiva (Postfix, from userid 0) id 1F1BC7C6DA; Wed, 26 Jan 2000 16:52:58 -0200 (BRDT) Date: Wed, 26 Jan 2000 16:52:58 -0200 From: Jorge Godoy <godoy@conectiva.com.br> To: Karl Eichwalder <ke@suse.de> Cc: Telsa Gwynne <hobbit@aloss.ukuu.org.uk>, gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000126165258.C5806@conectiva.com.br> References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> <shpuuoads4.fsf@Frechet.suse.de> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit X-Mailer: Mutt 1.0i In-Reply-To: <shpuuoads4.fsf@Frechet.suse.de>; from ke@suse.de on Wed, Jan 26, 2000 at 07:28:11PM +0100 X-Operating-System: Linux nexus.conectiva 2.2.13-10cl On Wed, Jan 26, 2000 at 07:28:11PM +0100, Karl Eichwalder wrote: > Telsa Gwynne <hobbit@aloss.ukuu.org.uk> writes: > > | One of those </>s was superfluous and removing that, and putting > | a </sect2>, elsewhere fixed a lot of it. But it took -ages-! > > You should have tried `sgmlnorm' first ;-) which come with the jade > package. As a suggestion, why don't you use only "<section>" instead of "<sect1>","<sect2>", etc.? <section> can be nested and it performs the same way as it's numbered friends plus adds the possibility of moving text without having to worry with it's nesting level. -- Godoy. <godoy@conectiva.com.br> GPG Fingerprint 851B B620 626D 2AD0 E783 "Ser poeta n�o � minha ambi��o, E932 1330 BE6D A4A3 0625 � minha maneira de estar sozinho" - Fernando Pessoa. Publica��es @ Conectiva S.A. Except where explicitly stated I speak on my own behalf. Exceto onde explicitado as declara��es aqui feitas s�o apenas minhas. From GLeblanc@cu-portland.edu Thu May 11 23:31:00 2000 Received: (qmail 12443 invoked from network); 26 Jan 2000 19:05:54 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 19:05:54 -0000 Received: from email.cu-portland.edu (email.cu-portland.edu [204.202.196.11]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA05240 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 14:05:53 -0500 Received: by email.cu-portland.edu with Internet Mail Service (5.5.2650.10) id <CDTB5FS5>; Wed, 26 Jan 2000 11:05:50 -0800 Message-ID: <A5F46F4ED18FD211ABEE00105AC6CF077F7B5D@email.cu-portland.edu> From: Gregory Leblanc <GLeblanc@cu-portland.edu> To: "Gnome Doc List (E-mail)" <gnome-doc-list@gnome.org> Subject: RE: Documentation templates and references Date: Wed, 26 Jan 2000 11:05:49 -0800 MIME-Version: 1.0 X-Mailer: Internet Mail Service (5.5.2650.10) Content-Type: text/plain; charset="windows-1252" -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 > -----Original Message----- > From: Karl Eichwalder [mailto:ke@suse.de] > Sent: Wednesday, January 26, 2000 10:26 AM > To: Joakim Ziegler > Subject: Re: Documentation templates and references > > > Joakim Ziegler <joakim@styx.net> writes: > > | In fact, if you avoid this and a couple of other SGML-specific > | constructs, you'll be able to port the SGML documents to > XML without > | any changes (except the header) when that day comes. > > . You'll have to change empty element tags nevertheless. > > . It will be easy to "convert" SGML documents to XML. > > . There will be no need to convert SGML documents; they will > stay valid > forever :) > > If a writer feels comfortable using SGML minimizations, he should > be allowed to use these features. Within reason. If we allow stupid ammounts of minimization as in the example that Telsa posted, then writing in SGML is little or no better than writing in plain text because we can't do anything with it. I'd agree that we shouldn't say "You CAN'T use SGML minimizations", but rather we should say, if you're going to use them, these are some guidelines that you really should follow. Greg -----BEGIN PGP SIGNATURE----- Version: PGPfreeware 6.5.1 for non-commercial use <http://www.pgp.com> iQA/AwUBOI9Fd5LW/u8jW+lnEQJGDACglMbTkJ2fjcTOmS6U+SRkD30a360AoKOu LPQC5HblPMk0NQgaapGWyPrI =Hxnl -----END PGP SIGNATURE----- From joakim@styx.net Thu May 11 23:31:00 2000 Received: (qmail 22797 invoked from network); 26 Jan 2000 19:20:35 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 19:20:35 -0000 Received: from relay1.mail.styx.net (nocto.styx.net [148.245.18.42]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA06173 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 14:20:34 -0500 Received: from login1.styx.net (login1.styx.net [148.245.18.30]) by relay1.mail.styx.net (Postfix) with ESMTP id DB6663100B for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:20:32 -0600 (CST) Received: by login1.styx.net (Postfix, from userid 5004) id 795026C035; Wed, 26 Jan 2000 13:20:32 -0600 (CST) Date: Wed, 26 Jan 2000 13:20:32 -0600 From: Joakim Ziegler <joakim@styx.net> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000126132032.A14171@styx.net> References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> <20000126104531.E1713@styx.net> <shu2k0adwh.fsf@Frechet.suse.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <shu2k0adwh.fsf@Frechet.suse.de>; from ke@suse.de on Wed, Jan 26, 2000 at 07:25:33PM +0100 On Wed, Jan 26, 2000 at 07:25:33PM +0100, Karl Eichwalder wrote: > Joakim Ziegler <joakim@styx.net> writes: >| In fact, if you avoid this and a couple of other SGML-specific >| constructs, you'll be able to port the SGML documents to XML without >| any changes (except the header) when that day comes. > . You'll have to change empty element tags nevertheless. Not necessarily. For instance, <foo></foo> is just as valid as <foo/> for an element defined as EMPTY. This is, I suspect, done to improve SGML interoperability. > . It will be easy to "convert" SGML documents to XML. > . There will be no need to convert SGML documents; they will stay valid > forever :) If tools and stylesheets change to become XML-centric, this need might arise. > If a writer feels comfortable using SGML minimizations, he should be > allowed to use these features. I definitely think the use should be minimized, or even abandoned altogether. It does nothing for readability, and the time savings are minimal. But I'll leave that decision up to others. -- Joakim Ziegler - styx research director - joakim@styx.net FIX sysop - FIXmud admin - FIDEL & Conglomerate developer From GLeblanc@cu-portland.edu Thu May 11 23:31:00 2000 Received: (qmail 149 invoked from network); 26 Jan 2000 20:21:25 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 20:21:25 -0000 Received: from email.cu-portland.edu (email.cu-portland.edu [204.202.196.11]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id PAA09871 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 15:21:24 -0500 Received: by email.cu-portland.edu with Internet Mail Service (5.5.2650.10) id <CDTB5FZP>; Wed, 26 Jan 2000 12:21:19 -0800 Message-ID: <A5F46F4ED18FD211ABEE00105AC6CF077F7B5E@email.cu-portland.edu> From: Gregory Leblanc <GLeblanc@cu-portland.edu> To: "Gnome Doc List (E-mail)" <gnome-doc-list@gnome.org> Subject: On the use of tag minimizations in DocBook Date: Wed, 26 Jan 2000 12:21:18 -0800 MIME-Version: 1.0 X-Mailer: Internet Mail Service (5.5.2650.10) Content-Type: text/plain; charset="iso-8859-1" -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Tag minimizations should be avoided if at all possible. The advantages of tag minimization are few, and the benefits of NOT using them far outweigh these comforts. Below are three examples, each using a different ammount of tag minimization, followed by a short explanation of what's good/bad about each. I'm not going to make any whitespace changes here, although I'll use the same example SGML for the whitespace example. This first one is stolen from the Balsa.sgml file in Balsa version 0.6.0. EXAMPLE 1 <sect2 id="cfgtab-mail-servers"> <title>Mail Servers</> <para>This page lets you specify how you get remove POP3 mail, send mail, etc.</> <variablelist> <varlistentry><term>Remote Mailbox Servers</><listitem><para>These are POP3 servers that you recieve email from. The three buttons let you create, modify, and remove records. POP3 mailboxes will not show up in the mailbox list.</></></> <varlistentry><term>Local Mail Directrory</><listitem><para>This is the directory that Balsa will scan looking for mail folders.</></></> <varlistentry><term>Remote SMTP Server</><listitem><para>If your computer is not equipped with sendmail or you do not wish to use it, select this radio button and enter a hostname to contact via SMTP.</></></> <varlistentry><term>Local Mail User Agent</><listitem><para>Balsa will attempt to use sendmail to send mail. Unfortunately, you cannot specify the command to execute right now.</></></> <varlistentry><term>Check Mail Automatically Every...</><listitem><para>If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. <note><para>Using "0" as an interval is a <emphasis>really</> bad idea.</></></></></> </> </> As you can see, with a bit of work, it's possible to understand where the elements start and end, but just from looking at this, it's not so obvious. If I open this file in an editor with decent syntax highlighting capabilities (emacs with psgml, others), it's much easier to read, but I still have to count the number of tags that are open and closed. Definately not the best SGML that I've ever seen, but it seems to work (mostly). EXAMPLE 2 <sect2 id="cfgtab-mail-servers"> <title>Mail Servers</> <para>This page lets you specify how you get remove POP3 mail, send mail, etc.</> <variablelist> <varlistentry><term>Remote Mailbox Servers</><listitem><para>These are POP3 servers that you recieve email from. The three buttons let you create, modify, and remove records. POP3 mailboxes will not show up in the mailbox list.</para></listitem></varlistentry> <varlistentry><term>Local Mail Directrory</><listitem><para>This is the directory that Balsa will scan looking for mail folders.</para></listitem></varlistentry> <varlistentry><term>Remote SMTP Server</><listitem><para>If your computer is not equipped with sendmail or you do not wish to use it, select this radio button and enter a hostname to contact via SMTP.</para></listitem></varlistentry> <varlistentry><term>Local Mail User Agent</><listitem><para>Balsa will attempt to use sendmail to send mail. Unfortunately, you cannot specify the command to execute right now.</para></listitem></varlistentry> <varlistentry><term>Check Mail Automatically Every...</><listitem><para>If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. <note><para>Using "0" as an interval is a <emphasis>really</> bad idea.</para></para></note></listitem></varlistentry> </variablelist> Well, I changed the tags on this one a bit, adding end tags to a lot of elements. I left a few elements without end tags, because they were close enough together to be obvious (only a couple of words in any tag), and all of the other tags were closed. This is a bit easier to read with a syntax highlighting editor, but that's always going to be the case with markup. This one is certainly acceptable, although perhaps not quite ideal. EXAMPLE 3 <sect2 id="cfgtab-mail-servers"> <title>Mail Servers

tages. There are several man2html tools around. For links to examples of the output of one, try: http://www.freeswan.org/freeswan_trees/freeswan-1.2/doc/manpages.html Those man pages are written and maintained by the programmers. The tech writer (me) created the index page and wrote about 10 lines of Makefile and shellscript calling man2html to produce the HTML man pages. Since then, the project lead has altered the scripts to improve the cross-referencing. It all works, our stuff is allGPL, and I think the man2html tool is too. There's an info2html tool available too. There is a lot of essential information in info files. What do you do with it? Rewriting it just to get it into a format that fits into your integrated list would be a horrible waste of resources. Persuade FSF that info is obsolete and should be replaced? That may not be easy and if you did manage it, you'd still have some problems. What's the new format and what do we do with the old info docs? Writing any automated info2whatever conversion toll would likely involve considerable work. No. Just use info2html and deliver the HTML. So I think we need a system that follows the old protocol builder's maxim "Be liberal in what you accept, be carefully limited in what you send out". Input: man/troff SGML/Linuxdoc SGML/Docbook info HTML add more as required and when resources are available Output: HTML That leaves two main problems. One is structuring the collection of HTML files. Your suggestions seem like an excellent starting point for that, but I need to both think more about it and hear what others have to say. The other is implementing various tools that would make this work. Quite a few pieces of it are out there. info2html. man2html, ... Several groups -- at least LDP, OSWG, and the BSD doc project I think -- have scripts that build large chunks of web sites with sgml2html tools. Those could likely be adapted to do another chunk of this. The FreeS/WAN distribution includes a tool of mine that generates a permuted index from headers in a group of HTML files. Quick and dirty code, needing work, but a starting point. FreeS/WAN also has a tool that post-processes html2man output and inserts additional links. The Amaya browser/editor from w3c.org has a handy "make book" feature. Build an index file using href tags with "rel=subdoc" attribute, load it in Amaya, hit "make book" on the menu and it replaces each such tag with the referenced file, adjusting links as required and optionally producing a table of contents for the whole thing. From ke@gnu.franken.de Thu May 11 23:30:59 2000 Received: (qmail 22796 invoked from network); 8 Jan 2000 06:32:07 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 8 Jan 2000 06:32:07 -0000 Received: from rachael.franken.de (rachael.franken.de [193.175.24.38]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id BAA00542 for ; Sat, 8 Jan 2000 01:32:06 -0500 Received: by rachael.franken.de via sendmail with stdio id for gnome-doc-list@gnome.org; Sat, 8 Jan 2000 07:32:04 +0100 (MET) (Smail-3.2 1996-Jul-4 #4 built DST-Sep-8) Received: from chico.franken.de(193.175.24.33) via SMTP by rachael.franken.de, id smtpdAAAa13278; Sat Jan 8 07:31:09 2000 Received: by chico.franken.de with UUCP for gnome-doc-list@gnome.org id m126pP2-005CQ0C; Sat, 8 Jan 2000 07:31:08 +0100 (MET) Received: by tux.gnu.franken.de (Postfix, from userid 270) id 8A068DC245; Sat, 8 Jan 2000 06:22:49 +0100 (CET) Sender: ke@gnu.franken.de To: Sandy Harris Cc: gnome-doc-list@gnome.org Subject: info2html and Texinfo (Re: Linux Documentation Infrastructure) References: <387627B0.5C0890AF@dfusion.com.au> <38764BD6.A9274003@storm.ca> From: Karl EICHWALDER Date: 08 Jan 2000 06:22:49 +0100 In-Reply-To: Sandy Harris's message of "Fri, 07 Jan 2000 15:25:58 -0500" Message-ID: Lines: 53 User-Agent: Gnus/5.0803 (Gnus v5.8.3) Emacs/20.5 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii [I don't like the X-posting idea.] Sandy Harris writes: | There's an info2html tool available too. i2h is a work around only; only fixed font output, no pictures. `tex2html' (or , once improved, `makeinfo --html') are much better. | Persuade FSF that info is obsolete and should be replaced? Please, respect other people's decision; quite a lot authors like to write documentation using Texinfo. | Writing any automated info2whatever conversion toll would likely | involve considerable work. Never rely on the info _output_; you've to work with the Texinfo source files (.texi). Join the Texinfo mailinglist if you're interested in writing a texinfo2xml converter as a backend of makeinfo. In addition please note that some of us prefer to browse the Info tree (with Emacs) and dislike HTML files a lot (browsers don't have the ability to search through _all_ the files at once). That's why we are interested in docbook2texi or docbook2info as well -- a promissing project is already started. Enough criticizing so far. I like it that you think about the possibilities how to glue together all the written docs. I recommend to be a little bit patient and to wait until some W3C "standards" are finished (XLink, XPointer, XPath, XHTML -- hope I get the names right) and to do all the linking using XML tools; it looks as if most of these "standards" will be available next time this year. Also it's important to sort out wrong placed docu (I don't see the point why there's a need to write a PostgreSQL or a CVS Howto and to distribute it with the specialized _Linux_ Howtos...). | The Amaya browser/editor from w3c.org has a handy "make book" | feature. Build an index file using href tags with "rel=subdoc" | attribute, load it in Amaya, hit "make book" on the menu and it | replaces each such tag with the referenced file, adjusting links as | required and optionally producing a table of contents for the whole | thing. I don't know whether this is a useful feature but it sounds very interesting:) -- work: ke@suse.de | : http://www.suse.de/~ke/ | ------ ,__o personal: ke@gnu.franken.de | ------ _-\_<, : http://www.franken.de/users/gnu/ke/ | ------ (*)/'(*) From kim@new-smtp2.ihug.com.au Thu May 11 23:30:59 2000 Received: (qmail 32023 invoked from network); 8 Jan 2000 08:30:33 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 8 Jan 2000 08:30:33 -0000 Received: from new-smtp2.ihug.com.au (root@new-smtp2.ihug.com.au [203.109.250.28]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id DAA04551 for ; Sat, 8 Jan 2000 03:30:30 -0500 Received: from dfusion.com.au (IDENT:kim@p9-max9.syd.ihug.com.au [206.17.105.73]) by new-smtp2.ihug.com.au (8.9.3/8.9.3) with ESMTP id TAA27373; Sat, 8 Jan 2000 19:29:42 +1100 Sender: kim@new-smtp2.ihug.com.au Message-ID: <3876F51E.3DF0E10E@dfusion.com.au> Date: Sat, 08 Jan 2000 08:28:14 +0000 From: Kim Lester Organization: Datafusion Systems Pty Ltd X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.3.35 i686) X-Accept-Language: en MIME-Version: 1.0 To: oswg-discuss , gnome-doc-list , linuxkb-discuss , ldp-discuss , osrt Subject: Open Document Environment (ODE) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Thanks to all those who responsed! I've taken your ideas on board and included them below. Keep it up. To those of you who haven't had a chance yet, please respond and come on board. Now is the time before recommendations get set in stone! What we are trying to achieve ============================= To reiterate the point of this post: Stop evolving documentation systems and bring all the documentation together in one easy to access form. Let me summarise so far: A number ofgroups are working on mostly different aspects of either documentation itself or documentation retrieval etc. Who === The organisations that I am now aware of include: Linux Documaentation Project (LDP) http://www.ldp.org Linux Knowledge Base Project http://www.linuxkb.org Gnome Documentation Project (GDP) http://www.gnome.org Open Source Research Team http://metalab.unc.edu/osrt/projects.html Open Software Writers Group http://www/oswg.org Interest has also been shown by an electronic publisher to produce hardcopy versions of the resulting high-quality documentation. If you know of any (non-commerical) doc group that I've left out please let me/them know. How === I'm not even going to attempt all this on my own, if the community can't be far-sighted enough and altrusitic enough to help then the task will be futile. I'd at least hope for enlightened self-interest! :-) Ultimately we could create a new mailing list covering all member groups, perhaps with the other existing groups as subgroups of this. I'm currently forcing it on you for now as we keep getting new special interest document groups and no-one appears to have shown interest in cooperating. I have joined the LDP, GDP, LKBP OSWG discussion groups and will cc this thread to all groups above (unless I get too many childish flames). I believe this is one of the few time when, what is effectively cross posting, is important to this community. To those of you in advance who are going to object to my cross posting invading your personal world, I'd say look around you. The best things in life, the web, Linux etc were made through cooperation. Maybe we all have to give a little ground but the result will be far better than any one group could have achieved on its own. I propose creating an umbrella group of which all (hopefully) the above groups would be members. This group would coordinate the infra-structure of all documentation, (ie the "ideal" format, the permitted formats, the indexing/xref'ing scheme papaer output etc). Once this has been dertermined (with all your input and expertise) everyone can, more-or-less get on with waht they were doing before, but in this agreed framework. WHY am I trying to do this ? ============================ This is a serious attempt at getting badly needed coordination. It is NOT about control. I am in no way interested in controlling anyone. I am interested in coordinating a unified effort with everyones help. I respect that each one of the above groups has slighty different goals. This is actually good as the task is large. If we change "goals" to "areas of responsibility" I think we could really get somewhere - together. I respect the amount of effort many of you have put in, in your own areas and groups. I do not wish to detract from that, nor do I wish to take away anything from the individual groups. It will take me a little while to digest all the different group areas, so bear with me on this, and help me out by becoming part of this discussion. NOTE: All the following is open to comment/suggestion. This has to be a community effort. I want to encourange informed debate, but not create a free-for-all anything-goes environment. This is counter-productive. Scope of Group ============== I've tentatively named the umbrella group "Open Documentation Environment (ODE)" Ode is also a relevant word. (Maybe for the trekkers amongst you it should be called "ODO" Open Doc Org. after all ODO is very flexible.... :-) ) I wanted to avoid using one of the existing group's names as experience indicates this leads to ownership issues. Humans can be difficult at times. Sigh! My initial area of interest was Linux and its software. However I realised that software like Gnome etc are broader than just linux. This is fine as the document infrastructure I'm proposing supports that. It does need to be said though that the system _may_ end up being used in other areas, we should encourage this and not be biased against it. In the first instance I suspect that most of the work will be done in the linux area though. General Design Goals ==================== * Implementation of a Bookshelf concept A bookshelp is a simple visual pardigm. There would be bookselves in a range of categories (eg End User, Administrator, Developer). Only the relevant Bookshelves need to be displayed (by default) for any user. Searches would also be confined to selected bookshelves. Books on any topic could be added to a bookshelf. General book writing guidelines would keep books releveant to their category. Bookshelves could be added to via a web site. Thus a user has a list of available books. Books would be installed wither locally, on a LAN or on the net. All would appear to the user. (Maybe different colours etc ro indicate local/LAN/web access etc). All this would be transparent to the user. Available book contents pages/indexes would automatically be downloaded and available for perusal. If a WEB based book looked interesting then either the whole book or just a few pages could be downloaded asrequired. Indexing/cross referencing should also provide the ability to show info (maybe in a pastel hue) of information on say software that is available but not installed. So many time users have not been aware of installed software let alone software avaialble on the net. For example if I wanted an image editor. I could ask for a search on "Image Editors (Raster)" and be told that I had say one on my system and 3 avaialble for download from the net. "Hmmm the installed one doesn't do what I wnat. But this other one interests me I'll download its overview page and maybe help contents. Looks good, ok go get it." I have dozens (probably hundreds of programs installed on my system) that I don't use. Why are they there? Because a) I might need them b) I don't know they're there. c) I don't need them but they were installed anyway because I didn't know any better It would be so much better to install just a few "common" apps and ta good documetnation system. Then have the others books/apps installed on demand. With the bookshelf system we have access to the docs of programs not installed so we don't ahve to worry about missing out (and often installing everything just to be sure)! Then we'd install just what we needed. NOTE: In the future this could also support download of commercial books/sw for a fee, but we won't deal with that for now. Books might actually consist of docuemnts that appear in several places as relevant. Eg a technical chapter on PPP configuration might appear as a document/book under Installation and also under Administration and even uder Operating System (internals). ALthough one has to be careful it can be taken too far. It is not a substitude for sloppy categorisation! SGI have/had a reasonable bookshelp concept, it would be useful to examine this for ideas. * All books/documents appear to be in ONE format (from reader's perspective). Ideally this means look at feel similar. I'm not suggesting that we enforce a specific look and feel, but that we conform to a set of directives (eg all titles have a TITLE tag) such that all titles can be made to look similar. Recommend a default look and feel (X windowing system made the mistake of not recommending a look and feel. The result was chaos for many years!) Books in a range of other formats are converted (one-time or on-the-fly) into the common format Human Issues ============ There are no doubt going to be some religous wars on formats. Some would rather die than give up their favourite format. Hopefully the converters will address some of these issues and permit personal preferences to prevail. HOWEVER. What I want us to achieve is something better for everyone. If you'd rather defend your personal rights to the death and refuse to be part of something bigger then I wish you good luck. But such attitudes tend to result in individuals and groups pushed towards the fringes rather than being in the main stream success. There are still people out there who think CPM (an early OS) is the best thing ever. Well I can appreciate their right to that belief, but they aren't interested moving forward. We will probably all have to give some ground for a common good... If you have a technically valid issue, join in the discussion and lets work it out! Working Group Tasks =================== The group should examine the skills and technologies of a) group members, b) other technology and come up with recommendations for: Initial Documentation Areas - split into broad subject areas right down to key topics. Documentation Technology - determine the best OUTPUT technology to support a) Good presentation b) hierarchical doc structure c) Extensive cross-referencing d) High Quality Printing - determine how best to massage existing formats into the new format. Identify existing documetn formats. (Important docs would need editing, others could be auto processed at least initially) Documentation "Browser" Technology. - determine specs for a world-class doc viewer/search-engine/etc that fits the chosen OUTPUT technology - take into account existing software but not be hamstrung by it. - might support basic browsing with existing software and more advanced functions with an open-source customised browser. - include any xref/search engine Legal Stuff =========== I hate layers, I hate legal documents. They often end up spoiling things. Everything seems to require some legal statement though.. The author maintains ownership of his/her document and authors name must always be included. Perhaps provide a history log of editors. If a doc becomes inaccurate then editing must be permitted regardless. (Seems a bit hard, but I'm tired of inaccurate docs that don't get changed). Note sure about aesthetic editing. I'm not sure whether docs should be allowedto have individual Licenses. Maybe just permit one or two common licenses (GNU ?). Licenses should permit free use/printing of docs for personal use. Non-profit distribution must also be royalty free. For-profit distribution (eg proper publishing) should perhaps be based on typical industry royalties and then percentages given either to key authors and/or the remainder put in something like an ODE non-rpofit fund to pay for even better doc. I'm aware of two other doc licenses: Open Content License and GNU Free Documentation License. I haven't read them yet. I'd welcome any better suggestions. The following are a zeroth order draft of the above areas, as somewhere to start. NOTE: To those of you not into Linux, please bear with me I have to start the discussion somewhere. I'd welcome contributions! Initial Documentation Areas =========================== Note keeps apps and utlitities separate from OS implementations where possible. eg the unix "date" command whilst compiled for and available under Linux is also available on any system compiling GNU tools. It should thus be available in a cross ref under "Linux->Commands" but if the linux specific docs are removed then it ought to remain available under the more general Unix->Commands. Note I haven't fully developed a plan for this yet. Initial Bookshelves ------------------- System Installation General User Guide Tools and Applications Administration Application Software Developer Operating System Operating System Developer Hardware There are a number of ways to divide bookshelves. I have initially divided them based on gut feeling from years of personal experience and problem solving for users. Tools and Apps are separate as all levels of users need to look up this info. Most of the bookshelves would have a combination of books that might come under the categories of Guides Reference System Installation ------------------- I guess this might be a separate bookshelf although parts of it come under Admin and parts user. Linux Installation i) General Linux Installation ii) Installation iii) Installation/Notes iv) Errata General User Guide ------------------ a) Desktop Environment Current (ie what is being run now) Others )other availabe environments) This should contain all the "getting to know you" stuff In particular it should distinguish between the current installed software and other options. It is important to distinguish the current environement setup from possible setups. It is too mcuh to expect a novice user to know that he/she is currently running Enlightenment WM on Gnome on X on Unix. Even I forget which WM I'm running half the time! The "Other" section would list alternives that the user might prefer to explore along with references to how to setup/install/activate these alternatives. Tools and Applications ---------------------- a) Major Applications Listed By Name Xref By Category (Word Process, Text Edit, Spreadsheet, Drawing) b) Utilities/Tools Listed by Name Listed by Category (Disk, Net, File Manip, Text Manip, etc) (Listed By Problem/Solution) c) Man pages Administration -------------- Key Topics/Overview Tasks by Topic a) Logs b) LAN c) Internet (SLIP/PPP etc) d) User Accounts e) Routine Maintenace f) Hardware Problems g) ... . z) (Man Pages) Application Software Developer ------------------------------ Language Summary/Overviews Languages... Debuggers (Man Pages) X11 Developer Gnome Developer Overview Style Guide API Reference KDE Developer Window Manager... Hardware Board Level Docs (disks, graphics cards etc) etc Documentation Technology ======================== Existing doc formats -------------------- plain text - some HOWTOs (semi structured) - READMEs/Changes/INSTALL instructions etc (semi structured) - FAQs (semi structured) - misc notes man pages - all command line unix commands custom application help HTML - some HOWTOs - some FAQs - Introductory Docs - Distribution docs (eg RedHat) texInfo SGML XML DocBook DTD (XML/SGML) (RPM) Proposed doc "OUTPUT" format ---------------------------- It has bveen suggested that there really isn't any excuse for plain text any more as a plain doc can be made at least HTML compliant with a couple fo minutes extra work. There are also man/html converters around so the man page format may not be as sacrosanct as once thoguht. (being able to see good ascii output when typing "man fred" is still a requirement though. It thus seems feasible to have a single "meta format". Ideally all documents would be in this format, and in time they might be, but for now there need to be converters from existing formats (may such beasts already exist). Whatever standard we agree upon as the meta/Output format it should be extensible and flexible enough to adapt to things that we havent thought of yet. Converters from existing formats to "OUTPUT" format --------------------------------------------------- Some existing document systems are extensive enough that conversion to a new format by hand could be prohibitive. Some docs may be converted one-time into the new format other (which are still being edited by other groups who can't/won't change formats might have to be converted on-the-fly from their native formats. Other docs should just be changed, either by authors or group members. Once there is enough momentum I envisage that encouraging many existing doc. maintainers to put in a little extra work for the good of all will become easier. My first guess for an output format would be XML possibly using the DocBook DTD (http://docbook.org/) maybe with some extra tags. Issues ------ Ease of adding/copying/indexing books Support transfer of just sections of a book (eg specific sections/pages) as required to be downloaded from the web - ie don't require whole book. It owuld be good to provide links from within apps to a common doc. set. Sometimes apps have internal help systems which are a) uselss as they tell you nothing much b) very helpful but not accessible outside the app. Lets pursue a policy of "write once, read many" (WORM - yes I know it comes from MO technology) ie maximise the access to any documentation. This could include context sensitive tags activated within an application that open up to a specific part of the application book. RPM --- Open to debate, but I added RPM to the "doc" list as it is becoming an increasingly important tool for the distribution of software. For those of you not familiar with it, RPM is a software distribution tool that pacakges up the files in a software/document/etc sub-system along with an info summary and installation scripts. RPM could be important in two areas: 1) it could be a convenient ODE Book distribution/installation/update mechanim. 2) it could provide a useful method of creating a "virtual" book of installed software. Of course installed software should have documentation pages under the new system but in the meantime RPM has at least a few lines of comments about each package and a broad category for that package (eg Applications/Internet). Browser Technology ================== Leverage existing efforts. Indexing/Cross Referencing -------------------------- Produce access to a comprehensive indexing system and permuted index etc. Here the expertise of the OSoRT group will greatly help! Indexing by Book/Doc Title book text concept keywords/category (eg Text Editors->Graphical" or "PPP Problems") The Gnome Help Browser might be a good GUI software vehicle with which to start experimenting. Initial GUI Thoughts -------------------- I'd like to see a doc browser a bit like one of MSoft's (eeek!) development doc system. The key idea is a panel at the left with a tree view and the document panel at the right. Might also have a separate document/book-chapter/section broswer to quickly pick out sections in the current book. regards Kim Lester From sandy@storm.ca Thu May 11 23:30:59 2000 Received: (qmail 13668 invoked from network); 8 Jan 2000 16:13:13 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 8 Jan 2000 16:13:13 -0000 Received: from mail.storm.ca (storm.ca [209.87.224.69]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA15317 for ; Sat, 8 Jan 2000 11:13:12 -0500 Received: from storm.ca (ppp003.ottawa.storm.ca [209.87.227.3]) by mail.storm.ca (8.8.8+Sun/8.8.8) with ESMTP id LAA07925; Sat, 8 Jan 2000 11:13:10 -0500 (EST) Message-ID: <38776248.645EB80B@storm.ca> Date: Sat, 08 Jan 2000 11:14:00 -0500 From: Sandy Harris Reply-To: ldp-discuss@lists.debian.org X-Mailer: Mozilla 4.7 [en] (Win98; U) X-Accept-Language: en,fr MIME-Version: 1.0 To: ldp-discuss@lists.debian.org CC: gnome-doc-list@gnome.org Subject: Re: info2html and Texinfo (Re: Linux Documentation Infrastructure) References: <387627B0.5C0890AF@dfusion.com.au> <38764BD6.A9274003@storm.ca> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Karl EICHWALDER wrote (on gnome-doc, cc'd to me): > [I don't like the X-posting idea.] Nor I. I'm cross-posting to two lists the original message went to (which I feel I should do so no-one interested misses out), then setting followup-to: in hopes of pointing future discussion to one place. > Sandy Harris writes: > > | There's an info2html tool available too. > > i2h is a work around only; only fixed font output, no pictures. > `tex2html' (or , once improved, `makeinfo --html') are much better. Better tools than the one I knew about. Great. > | Persuade FSF that info is obsolete and should be replaced? > > Please, respect other people's decision; quite a lot authors like to > write documentation using Texinfo. My point was that if you want a single /delivery/ format, Kim's list wasn't enough because it couldn't easily include all the existing docs whose source is in texinfo format. > | Writing any automated info2whatever conversion toll would likely > | involve considerable work. > > Never rely on the info _output_; you've to work with the Texinfo source > files (.texi). This is just a terminology error on my part. I said "info" since that's how I browse those files, and should have said "texinfo". > Join the Texinfo mailinglist if you're interested in > writing a texinfo2xml converter as a backend of makeinfo. > > In addition please note that some of us prefer to browse the Info tree > (with Emacs) The question on the table, I think, is how to deliver all docs for Linux or other open source OS's in a single integrated format. No-one is suggesting doing away with other formats. Man pages would remain available via the man command, texinfo via info or printed via tex, docbook in all its formats, ... The question is how to also deliver everything one some integrated accessible-to-all way. > and dislike HTML files a lot (browsers don't have the > ability to search through _all_ the files at once). That's one of the things we'd have to build for HTML to make this work. At the very least, someone would need to improve my tools that give a permuted index from tags in a set of HTML files to production quality we'd need an HTML-based equivalent of man -k, likely with extensions for docs not in man format a number of overview or index files linking things together would need to be written > That's why we are > interested in docbook2texi or docbook2info as well -- a promissing > project is already started. I don't think the universal delivery format can be info. To do that you'd need man2info as well as docbook2whatver, plus an info browser that's accessible to all. > ... I recommend to > be a little bit patient and to wait until some W3C "standards" are > finished (XLink, XPointer, XPath, XHTML -- hope I get the names right) > and to do all the linking using XML tools; it looks as if most of these > "standards" will be available next time this year. I'd prefer XML as well, but I'm not certain we can afford to wait. I'd say do what we can now with HTML, keeping in mind that we don't want to do anything that will make the XML conversion harder. > Also it's important to sort out wrong placed docu (I don't see the point > why there's a need to write a PostgreSQL or a CVS Howto and to > distribute it with the specialized _Linux_ Howtos...). I agree, though I can see e.g. including standard CVS docs in a Linux distribution and having a Linux HowTo that covers any Linux-specific stuff required to get it installed or to administer it. I'd go further and say that any tools developed for a single delivery format project should target at least *BSD as well as Linux. From ke@gnu.franken.de Thu May 11 23:30:59 2000 Received: (qmail 21696 invoked from network); 8 Jan 2000 17:43:36 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 8 Jan 2000 17:43:36 -0000 Received: from rachael.franken.de (rachael.franken.de [193.175.24.38]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA19947 for ; Sat, 8 Jan 2000 12:43:35 -0500 Received: by rachael.franken.de via sendmail with stdio id for gnome-doc-list@gnome.org; Sat, 8 Jan 2000 18:43:33 +0100 (MET) (Smail-3.2 1996-Jul-4 #4 built DST-Sep-8) Received: from chico.franken.de(193.175.24.33) via SMTP by rachael.franken.de, id smtpdAAAa17630; Sat Jan 8 18:42:54 2000 Received: by chico.franken.de with UUCP for gnome-doc-list@gnome.org id m126zt8-005ChsC; Sat, 8 Jan 2000 18:42:54 +0100 (MET) Received: by tux.gnu.franken.de (Postfix, from userid 270) id F0EC7DC244; Sat, 8 Jan 2000 18:40:45 +0100 (CET) Sender: ke@gnu.franken.de To: gnome-doc-list@gnome.org Cc: Sandy Harris Subject: Re: info2html and Texinfo (Re: Linux Documentation Infrastructure) References: <387627B0.5C0890AF@dfusion.com.au> <38764BD6.A9274003@storm.ca> <38776248.645EB80B@storm.ca> From: Karl EICHWALDER Date: 08 Jan 2000 18:40:45 +0100 In-Reply-To: Sandy Harris's message of "Sat, 08 Jan 2000 11:14:00 -0500" Message-ID: Lines: 56 User-Agent: Gnus/5.0803 (Gnus v5.8.3) Emacs/20.5 MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable Sandy Harris writes: Yes, I know it wasn't you in the first place who does the X-posting. | The question on the table, I think, is how to deliver all docs for | Linux or other open source OS's in a single integrated format. IMO, the decision at this moment is quite easy. Make sure that's possible to convert all docs into good XML files. | I'd prefer XML as well, but I'm not certain we can afford to wait. I'm convinced it's worth to do so. In the mean time we should try to study the 4 "standard" (drafts/recommendations) at W3C I named. XHTML is a fun to read (I've done so around Xmas). Norman Walsh already started to work on docbook-to-xhtml style sheets :-) The 5th document to think about is this one (I didn't read it until now): >>> What are Topic Maps? 'Topic Maps' is a new international standard (ISO/IEC 13250) for layering multidimensional topic spaces on top of information assets. The standard covers concepts like topics, associations, occurrences and facets/metadata. Topic Maps are expected to have a major impact on future information systems. [...]

= tmproc 0.20 - an implementation of Topic Maps, a new international standard (ISO/IEC 13250:1999) for layering multidimensional topic space= s on top of information assets. (14-Jul-1999) [Quote from Geir Ove Gr=F8nmo, ANN: tmproc 0.20, a Topic Maps implementation [note by me: this ANN is python related].] | I agree, though I can see e.g. including standard CVS docs in a | Linux distribution and having a Linux HowTo that covers any | Linux-specific stuff required to get it installed or to administer | it. Yes. | I'd go further and say that any tools developed for a single | delivery format project should target at least *BSD as well as | Linux. I don't mind this idea. --=20 work: ke@suse.de | : http://www.suse.de/~ke/ | ------ ,__o personal: ke@gnu.franken.de | ------ _-\_<, : http://www.franken.de/users/gnu/ke/ | ------ (*)/'(*) From aturner@linuxkb.org Thu May 11 23:30:59 2000 Received: (qmail 27525 invoked from network); 9 Jan 2000 09:05:29 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 09:05:29 -0000 Received: from vodka.linuxkb.org (foobar@vodka.linuxkb.org [205.231.210.90]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id EAA19010 for ; Sun, 9 Jan 2000 04:05:28 -0500 Received: (qmail 1587 invoked by uid 10024); 9 Jan 2000 09:05:21 -0000 Date: Sun, 9 Jan 2000 01:05:21 -0800 (PST) From: Aaron Turner To: linuxkb-discuss cc: oswg-discuss , gnome-doc-list , ldp-discuss , osrt Subject: Re: Open Document Environment (ODE) In-Reply-To: <3876F51E.3DF0E10E@dfusion.com.au> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Hi Kim & world, Well here's my thoughts in no particular order: 0) I think a global mailing list for those projects interested in this is in order. I know I'll subscribe. I'm sure I can get Roger from SEUL to sponsor the list on his mail server unless someone feels strongly another way. odo@seul.org perhaps? Or lodo for Linux Open Doc Org.? 1) Having one specific format (Docbook for example) is great from an indexing and searching perspecitive. As the person in charge of the LKBP's search engine, I've given a lot of thought to how I can make the searches more meaningful to the user and more accurate. One of the biggest improvements in this area come when you have a standard format such as Docbook and then give your search engine the intelligence to understand it. It's also a lot of work :) 2) Having one specific format is less than ideal from an authors perspective. Telling someone how to move a filesystem from one partitition to another takes less than a page, and forcing them to use a relatively complicated markup such as Docbook is a good way to get the author to decide it's not worth the effort. And of course there are a lot of people who don't know things like Docbook and they don't really have the time. There are ways to get around this sort of thing, people who manually convert them for the original author and things like that. As it stands now, the LKBP is more of a generalized search engine- that is to say, we don't care what the format of the document is, as long as it can be represnted on a web page. Also, if you're storing the content in a (SQL?) database it may be preferable to use the fields of the database for structure rather than using something like docbook for specifying the Title, Author, Date, etc info as there are very few XML aware DB's out there. Basically, we need to think this out really really well. 3) Licenses are a kicker. The LKBP has a license based on the Netscape Open Directory Licnese. I think a license such as this is more applicable to such a project, since it's the categorization of the content that makes it valuable. There is tens of thousands of docs for linux around the web, the reason they're not of much use is that people can't find them. Generally allowing a number of pre-approved licenses for the actual content should be good enough. Do we really want to read each person's license (which may or may not be a well written license in the first place) to make sure it meets our requirements? Not me. That and license creep (the creation of more and more licenses) is generally a bad thing. 4) Creating a new umbrella group is good. 5) Keeping a Linux slant on things IMHO is a good thing. I assume that if the FreeBSD users want's something like the LKBP or what you suggest they can download the source code to the site, download the database, weed out what they don't want and add in FreeBSD specific stuff. This makes things more meaningful for the end user. 6) The Bookshelf analogy has some merit, but I feel (at least right now, subject to change without notice) that the basic categorization ala Yahoo is the right way to go. Yahoo has been sucessful for a number of reasons, one of which is that it's simple to find what you're looking for. Complicated analogies which have color coded sections and things like that are confusing, and finding a solution to a problem should be simple and streamlined, almost wizard-like. Not to say a more powerful/advanced search system isn't useful, but you need to provide a system that makes it 1-2-3 easy for "newbies". Or maybe I'm the only person who can never find what I'm looking for at the library. :) 7a) Local/LAN/WAN retreval is going to be hard. To build a scalable infrastructure like this is a huge effort. I've talked to people about things like this before, and looked at all sorts of ideas for doing it (everything from doing it via DNS, LDAP, and a cluster of SQL servers). It also makes version control, re-categorization, and data replication more many times more difficult since the content is distributed. Realize that 99.99% of the people will never install it locally and probably about 98% will not install it on their LAN. So why increase the difficulty of the project many times over for about 2% of the users? I think there are a number of more useful features that will be easier to impliment and will help more people. Keeping all the data on the sever makes life much easier. 7b) One thing I do think is really important though is allowing software developers to write programs that query such a site. Either general help systems or application help systems. This is pretty easy actually- you write an OpenAPI running over http that queries the site and leave the formatting up to the app. This way people can continue to distribute documents with software, but the user isn't limited to accessing only those documents. This is one of the projects for the LKBP, but our developer on this has had to stop development for personal reasons. 8) Knowing what software is installed on a users computer and then showing what documentation relates to that is rather interesting. Very interesting actually. It's also has a ton of privacy vs. usability issues too. Things like RPM make this a real possibility though. One of the things you could do is create user accounts on the server, and allow people to upload their RPM databases, then do a xref search based on that. At least that way you can allow people to op-in to something like this. We could also provide summary usage stats back to the authors/interested persons for each piece of software- again, opt-in of course. It would be very cool to pull this off though. 9) Allowing the same document to live in two or more categories is key as what makes sense to you or me might be different from someone else. Each document should live wherever it makes sense. One thing you have to do though is make sure if someone does a search from a point in the tree where the same document is multiple places below it, you *MUST* weed out duplicates. 10) I haven't ever seen SGI's bookshelf thingy or heard anything about it. Maybe you could take a few screenshots for those like me who have no access to SGI/Irix?? Maybe after I see it I'll sing a different tune. 11) Having a common look and feel for all documents is good, but it really depends on what you want to do though. People who spend 10 minutes to write a simple FAQ aren't going to concern themselves too much with look and feel since it's not that important for a one page explaination. Sometimes standardization is taken too far at the cost of ease of use. Also do you not want to accept documentation just because it's not in the "approved format/structure"? man pages come to mind as one example. 12) It has to be scalable. No point in doing this if you can't scale the system/backend to 100,000+ documents of 1-1,000K in size. Simple static indexed sites such as the LDP or the Red Hat Linux Users FAQ (http://www.pobox.com/~aturner/RedHat-FAQ/) won't cut it. It's gotta have a database for the backend, preferably SQL or possibly LDAP. 13) Should have a internal means of keeping revision history. Not required, but nice. 14) Document Browser should be a web browser initially. Once you start requiring end users to install special software that has other requirements (such as a viewer using the GTK or QT libraries), your potential userbase shrinks. Should be Lynx friendly. 15) I think overall this is a great idea. I've thought about this for sometime myself, but have been too distracted in trying to get the LKBP out the door in at least an alpha state that I haven't had the time to be an ambassador to create the interest in something of this magnitude. Kinda the "If you build it they will come." mentality. I'm more than happy to jump on the bandwagon though. Anyways, those are my ideas- sorry if they're schitzophrenic, but I've had to write this email in 3 different sessions over a 24 hour period. -- Aaron Turner, Core Developer http://vodka.linuxkb.org/~aturner/ Linux Knowledge Base Organization http://linuxkb.org/ Because world domination requires quality open documentation. aka: aturner@vicinity.com, aturner@pobox.com, ion_beam_head@ashtech.net The difference between `Unstable' and `Usable' is only two characters: NT From gferg@hoop.timonium.sgi.com Thu May 11 23:30:59 2000 Received: (qmail 16783 invoked from network); 9 Jan 2000 16:43:10 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 16:43:10 -0000 Received: from sgi.com (sgi.SGI.COM [192.48.153.1]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA31572 for ; Sun, 9 Jan 2000 11:43:06 -0500 Received: from webster.timonium.sgi.com ([169.238.21.2]) by sgi.com (980327.SGI.8.8.8-aspam/980304.SGI-aspam: SGI does not authorize the use of its proprietary systems or networks for unsolicited or bulk email from the Internet.) via SMTP id IAA01855; Sun, 9 Jan 2000 08:42:06 -0800 (PST) mail_from (gferg@hoop.timonium.sgi.com) Received: from hoop.timonium.sgi.com by webster.timonium.sgi.com via ESMTP (950413.SGI.8.6.12/911001.SGI) id MAA07311; Sun, 9 Jan 2000 12:05:18 -0500 Received: by hoop.timonium.sgi.com (950413.SGI.8.6.12/940406.SGI.AUTO) id LAA11189; Sun, 9 Jan 2000 11:44:56 -0500 From: "Greg Ferguson" Message-Id: <10001091144.ZM11187@hoop.timonium.sgi.com> Date: Sun, 9 Jan 2000 11:44:56 -0500 In-Reply-To: Aaron Turner "Re: Open Document Environment (ODE)" (Jan 9, 1:05am) References: X-Mailer: Z-Mail (3.2.3 08feb96 MediaMail) To: Aaron Turner , linuxkb-discuss , ldp-discuss@lists.debian.org Subject: Re: Open Document Environment (ODE) Cc: oswg-discuss , gnome-doc-list , osrt Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii On Jan 9, 1:05am, Aaron Turner wrote: > Subject: Re: Open Document Environment (ODE) > ... > 7a) Local/LAN/WAN retreval is going to be hard. I think people need a retrieval capability that scales. It should (must?) work in all these situations. One huge master site (albeit mirrored in other locations) certainly makes life easier for the administrators of such a system. But, I should be able to examine/peruse just the content I have locally and then be able to jump to the site-based content store and/or "master" collection when desired. > 8) Knowing what software is installed on a users computer and then > showing what documentation relates to that is rather interesting. > Very interesting actually. It's also has a ton of privacy vs. > usability issues too. Have you seen the work of the Dublin Core group, the work done by Debian Doc project or what has been done by Paul Jones and the crew at Metalab? If not, you should examine these documents, which describe a methodology for "resource discovery". We, too (SGI) are incorporating a paradigm such as this in the Linux documentation and products we are currently preparing for release: Debian Metadata Project http://www.debian.org/~aph/debian-metadata.html/ Version 1.0 LDP CORE Specification http://metalab.unc.edu/osrt/ldpcore/ldp_elements Dublin Core Metadata Initiative http://purl.org/dc/documents/rec-dces-199809.htm Any such system should work with some sort of convention as described by these projects. The Open Ebook standard 1.0 also enables such a capability in it's system. > 10) I haven't ever seen SGI's bookshelf thingy or heard anything > about it. Maybe you could take a few screenshots for those like > me who have no access to SGI/Irix?? Maybe after I see it I'll sing > a different tune. Although a version of the system we provide does indeed scale down to a local system, our "main" site can be accessed with any old web browser from: htp://techpubs.sgi.com You can home to our Linux collection of documents from this URL: http://techpubs.sgi.com/library/tpl/cgi-bin/init.cgi?coll=linux > 15) I think overall this is a great idea. I've thought about this for > sometime myself, but have been too distracted in trying to get the LKBP > out the door in at least an alpha state that I haven't had the time to be > an ambassador to create the interest in something of this magnitude. > Kinda the "If you build it they will come." mentality. I'm more than > happy to jump on the bandwagon though. As am I! I think a new, neutral project is probably the appropriate way to approach this. I'm ready and willing to contribute in any way necessary. I basically worked on the design and code for SGI's aforementioned implementation, including the search engine/etc. best regards, -- Greg Ferguson - s/w engr / mtlhd | gferg@sgi.com SGI Tech Pubs - http://techpubs.sgi.com | 410-785-2334 Linux Doc Project - http://www.linuxdoc.org | From aturner@linuxkb.org Thu May 11 23:30:59 2000 Received: (qmail 30778 invoked from network); 9 Jan 2000 20:01:22 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 20:01:22 -0000 Received: from vodka.linuxkb.org (foobar@vodka.linuxkb.org [205.231.210.90]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id PAA05909 for ; Sun, 9 Jan 2000 15:01:21 -0500 Received: (qmail 3380 invoked by uid 10024); 9 Jan 2000 20:01:20 -0000 Date: Sun, 9 Jan 2000 12:01:19 -0800 (PST) From: Aaron Turner To: Greg Ferguson cc: linuxkb-discuss , ldp-discuss@lists.debian.org, oswg-discuss , gnome-doc-list , osrt Subject: Re: Open Document Environment (ODE) In-Reply-To: <10001091144.ZM11187@hoop.timonium.sgi.com> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On Sun, 9 Jan 2000, Greg Ferguson wrote: > On Jan 9, 1:05am, Aaron Turner wrote: > > Subject: Re: Open Document Environment (ODE) > > ... > > 7a) Local/LAN/WAN retreval is going to be hard. > > I think people need a retrieval capability that scales. It > should (must?) work in all these situations. One huge master > site (albeit mirrored in other locations) certainly makes > life easier for the administrators of such a system. But, I > should be able to examine/peruse just the content I have > locally and then be able to jump to the site-based content > store and/or "master" collection when desired. Hmmm... I guess I believe that if we get together and work together a number of things will happen: 1) We will have one of the most kick-ass document retrival engines on the web. We're not talking putting a bunch of files in a directory, and then having ht://Dig index them so you can do keyword searches. MUCH more powerful than that. 2) We will have THE most comprehensive archive of documentation for Linux on the web. This means a very complicated and difficult to setup web site with 100's of megabytes of data. Avg. Joe User isn't going to install the system (unless we make it really easy) and isn't going to want to download that much content over a 56K modem (or worse). Now maybe if we can get someone to sponsor a CDROM with the site on it that people could buy cheap that would work, and we could do quarterly updates or something. Now I'm not saying that we can't our shouldn't do this. I agree that it would be a great feature to offer the end user. (I should've been more clear about that last time- sorry.) I'm concerened about doing this as I know from experiance that this is not something simple to do, and I don't want to try to bite off too much initially. I will admit that there is a definate problem with this thinking- distributability can't be done correctly as an afterthought. If you don't build a system that is distributable to begin with, we'll probably end up throwing it out and starting over. That sucks. > > 8) Knowing what software is installed on a users computer and then > > showing what documentation relates to that is rather interesting. > > Very interesting actually. It's also has a ton of privacy vs. > > usability issues too. > > Have you seen the work of the Dublin Core group, the work > done by Debian Doc project or what has been done by Paul > Jones and the crew at Metalab? If not, you should examine > these documents, which describe a methodology for "resource > discovery". We, too (SGI) are incorporating a paradigm such > as this in the Linux documentation and products we are currently > preparing for release: [snip] I took a quick look at the links, and I'm not sure how that would help discovery of what applications/utilities/etc are installed on a clients system as it doesn't seem to have any provisions for communications between client and server, not to mention it is very documentation centric not application centric. (Or am I missing something?) Also, why re-invent the wheel, when things like RPM (and I assume the deb format does too) has a database with name and version information of nearly all software installed? The information we desire is a mere `rpm -qa` away. Now I do see where something like the above could be used for distributed content management. > > 10) I haven't ever seen SGI's bookshelf thingy or heard anything > > about it. Maybe you could take a few screenshots for those like > > me who have no access to SGI/Irix?? Maybe after I see it I'll sing > > a different tune. > > Although a version of the system we provide does indeed scale > down to a local system, our "main" site can be accessed with > any old web browser from: > > htp://techpubs.sgi.com > > You can home to our Linux collection of documents from this URL: > > http://techpubs.sgi.com/library/tpl/cgi-bin/init.cgi?coll=linux Kim, is this what you're talking about when you say bookshelf? I guess I really don't care for this. It's based too much on indexing alphabetically, and has zero categorization by subject type. Instead it's categorized by document type (man page, howto's, etc). Take the first entry in the Howto section for example "A mSQL and perl Web Server Mini HOWTO". This is horribly indexed under A IMHO. It should be indexed under DB's and then again under "Web Severs" or something like that. It also doesn't scale to 1000's of documents because the index is so flat. -- Aaron Turner, Core Developer http://vodka.linuxkb.org/~aturner/ Linux Knowledge Base Organization http://linuxkb.org/ Because world domination requires quality open documentation. aka: aturner@vicinity.com, aturner@pobox.com, ion_beam_head@ashtech.net The difference between `Unstable' and `Usable' is only two characters: NT From mwilson@real.com Thu May 11 23:30:59 2000 Received: (qmail 32369 invoked from network); 9 Jan 2000 20:08:03 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 20:08:03 -0000 Received: from prognet.com (mail-out.real.com [205.219.198.3]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id PAA06180 for ; Sun, 9 Jan 2000 15:08:02 -0500 Received: from granola.prognet.com (mwilson@[172.20.50.131]) by prognet.com (8.9.2/8.9.0) with ESMTP id MAA29181; Sun, 9 Jan 2000 12:07:14 -0800 (PST) Date: Sun, 9 Jan 2000 12:03:52 -0800 (PST) From: Matthew Wilson X-Sender: mwilson@granola.prognet.com To: Aaron Turner cc: linuxkb-discuss , oswg-discuss , gnome-doc-list , ldp-discuss , osrt , recipient list not shown: ; Subject: Re: Open Document Environment (ODE) In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Hey everyone, > 1) Having one specific format (Docbook for example) is great from an > indexing and searching perspecitive. As the person in charge of the > LKBP's search engine, I've given a lot of thought to how I can make the > searches more meaningful to the user and more accurate. One of the > biggest improvements in this area come when you have a standard format > such as Docbook and then give your search engine the intelligence to > understand it. It's also a lot of work :) I agree that having one format is essential to the success of any documentation system. However, as it seems that sgml-tools is no longer being supported (I tried every version on my clean slackware box, and *none* of them would compile/install/work) Perhaps we should try to move away from SGML/DocBook, and go with XML. Although XML is still in it's infancy, I believe that it would be an excellent platform to develop documentation with. XML is an open standard, heavily supported by many in the computer industry. Even the next generation of web browsers will be able to read it natively to some degree. It's also highly structured, designed from the beginning to be processed into other forms. All we would need to do is pick/create a suitable DTD. As for DocBook/Linuxdoc in sgml, since the current bulk of LDP documentation is in sgml, perhaps we would need either a conversion effort (automated?) or a grandfathering system. The whole point is that I think that we should not rely on software that is no longer being maintained (as sgml-tools has not been for some time) especially when so many people have so much trouble installing it. (I'm not the only one) Matthew From gleblanc@guppy.pond.net Thu May 11 23:30:59 2000 Received: (qmail 8257 invoked from network); 9 Jan 2000 20:27:05 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 20:27:05 -0000 Received: from guppy.pond.net (guppy.pond.net [205.240.25.2]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id PAA06944 for ; Sun, 9 Jan 2000 15:27:04 -0500 Received: from cu-portland.edu (snapuser2.pacificcrest.net [216.36.24.2]) by guppy.pond.net (8.9.3/8.9.3) with ESMTP id MAA00959; Sun, 9 Jan 2000 12:19:29 -0800 (PST) Sender: gleblanc@guppy.pond.net Message-ID: <3878EED6.72601D35@cu-portland.edu> Date: Sun, 09 Jan 2000 12:25:58 -0800 From: Gregory Leblanc X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.13 i586) X-Accept-Language: en MIME-Version: 1.0 To: Matthew Wilson CC: Aaron Turner , linuxkb-discuss , oswg-discuss , gnome-doc-list , ldp-discuss , osrt Subject: Re: Open Document Environment (ODE) References: Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Matthew Wilson wrote: > > Hey everyone, > > > 1) Having one specific format (Docbook for example) is great from an > > indexing and searching perspecitive. As the person in charge of the > > LKBP's search engine, I've given a lot of thought to how I can make the > > searches more meaningful to the user and more accurate. One of the > > biggest improvements in this area come when you have a standard format > > such as Docbook and then give your search engine the intelligence to > > understand it. It's also a lot of work :) > > I agree that having one format is essential to the success of any > documentation system. However, as it seems that sgml-tools is no longer > being supported (I tried every version on my clean slackware box, and > *none* of them would compile/install/work) Perhaps we should try to move > away from SGML/DocBook, and go with XML. Although XML is still in it's > infancy, I believe that it would be an excellent platform to develop > documentation with. > > XML is an open standard, heavily supported by many in the computer > industry. Even the next generation of web browsers will be able to read > it natively to some degree. It's also highly structured, designed from > the beginning to be processed into other forms. All we would need to do > is pick/create a suitable DTD. I hate to reply to a thread this huge and unweildy (is there going to be a mailing list for it soon?), but I really don't think that we should be moving to XML at this point. I'm currently using both sgml-tools and sgmltools on my RH linux machine, and although I don't have them on Solaris yet, I don't think that it's impossible. I don't know of any tools that can use XML at this point, except for Microsoft Internet Explorer 5. SGMLTools works, and can probably be made to work on Slack with some help from the mailing list. Also, I haven't seen either an ISO or W3C document on XML as a "standard", can you point me in the right direction? Proposals are there, but nothing official last I heard. > > As for DocBook/Linuxdoc in sgml, since the current bulk of LDP > documentation is in sgml, perhaps we would need either a conversion effort > (automated?) or a grandfathering system. I think that once the LDP has moved to the SGML DocBook DTD, and once there is an XML DocBook DTD, this conversion will be VERY easy. Before then, things could be ugly, depending on what XML DTD is chosen. I tend to think we should stick with/wait for DocBook, it's a very nice DTD for technical writing. > > The whole point is that I think that we should not rely on software that > is no longer being maintained (as sgml-tools has not been for some time) > especially when so many people have so much trouble installing it. (I'm > not the only one) What software do we have that IS being maintained for XML? Anybody who is running an RPM or deb based system can get packages for SGML-Tools (v1), and there is an RPM available for SGMLTools (v2). Anyway, get some specific details to the sgmltools mailing list, and I expect that you can get it to build. Again, sorry for this going to so many lists, Greg From deb@mail.redhat.com Thu May 11 23:30:59 2000 Received: (qmail 13321 invoked from network); 9 Jan 2000 20:33:42 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 20:33:42 -0000 Received: from smtp.linuxcare.com (qmailr@[216.88.157.131]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id PAA07258 for ; Sun, 9 Jan 2000 15:33:38 -0500 Received: (qmail 30893 invoked from network); 9 Jan 2000 20:36:53 -0000 Received: from mg128-172.ricochet.net (HELO linuxcare.com) (deb@204.179.128.172) by smtp.linuxcare.com with SMTP; 9 Jan 2000 20:36:53 -0000 Sender: deb@mail.redhat.com Message-ID: <3878F1BE.871618E4@linuxcare.com> Date: Sun, 09 Jan 2000 15:38:22 -0500 From: Deb Richardson Organization: Linuxcare X-Mailer: Mozilla 4.51 [en] (X11; I; Linux 2.2.5-15 i686) X-Accept-Language: en MIME-Version: 1.0 To: oswg-discuss@thepuffingroup.com CC: linuxkb-discuss , gnome-doc-list , ldp-discuss , osrt Subject: Re: [oswg-dis] Re: Open Document Environment (ODE) References: Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit There are a number of problems with the ODE proposal that I believe are likely to be insurmountable. I could be wrong, but I'll outline them here so we can discuss them. To be honest, I am unconvinced that creating an "umbrella group" such as this is necessary, or even that it's a good idea. Open Source and related projects work because they tend to not be monolithic, their infrastructures are usually simple and make use of well-known technologies, and there is little implication of there being a heirarchy of people and projects. On the other hand, I do feel that developing a set of standards for Open Source and Open Content documentation could be extremely useful. Having a commonly used set of standards would be very powerful. But creating a new organization for the development and maintenence of these standards is much more complicated (both practically and politically) than folks might suspect. If we are going to work towards the development of a set of standards for Linux documentation (which seems to be the gist of the discussion so far -- the FreeBSD and other folks are being left out at this point), I think we should develop these standards in cooperation with an existing group, such as the Linux Standard Base. The LSB website can be found at http://www.linuxbase.org. The LSB is an orgazation working to develop and promote a set of standards that will increase compatibility among Linux distributions that will enable software applications to install and run on any compliant Linux system. The LSB is already being supported by a large number of companies and organizations, including Linuxcare, Corel, the Debian Project, TurboLinux, VA Linux, SGI, Software in the Public Interest, Red Hat, and more. Are documentation standards within the current scope of the LSB? Not that I know of. But I cannot imagine that the LSB would be unwilling to examine a proposal and work with us to develop and promote whatever standards we devise. As for the development of standardized tools -- well, this is definitely outside the scope of the LSB. It is also a very non-open-source idea -- one of the beautiful things about Open Source is that it provides a user with choice -- a choice of distributions, of packages, of licenses, of programs, etc. We don't need a standardized tools if we have an open documentation standard that is supported and promoted by the majority of Open Source/Linux documentation projects. One standard, used as the basis of even hundreds of different tools, is good enough. As long as the tools are compliant with the standard, that is. People will be able to choose from among these tools to find those which best suit their own needs, systems, and work preferences. The idea of a "bookshelf" is a bit shortsighted. The majority of Open Source docs are delivered and used in electronic formats. The whole idea of a "book" is somewhat antiquated in the face of these electronic formats. Also, if you look around, the Open Source documentation community (the volunteer writers, editors, etc) have produced few large works. Most of the documents we have are short -- HOWTOs, MiniHOWTOs, FAQs, etc. There's a reason for this -- writing documentation is hard. Writing short, focused, procedural-style documents is simply easier than writing a book. It takes a great deal of time, dedication, and bloody hard work to produce a book. You're going to find precious few people who are going to volunteer their time to do so. So, why not have a bunch of volunteers collaborate on a single monolithic work? It's more likely that such a project would be successful, but there's still a lot of work that goes into developing, coordinating, and maintaining such a project. And the result is still a "book" which, as I've mentioned, is a bit limited given the power and flexibility of electronic formats. I do _strongly_ support the idea of using DocBook as a document format standard. Aaron mentioned that having to do short docs using DocBook would be a bit of a pain. That's true. Using DocBook to markup long docs is a bit of a pain, to be honest. But the results are worth the effort. SGML is a very very powerful tool. Used properly it can make cross-referencing, indexing, and other stuff happen as if by magic. I cannot express strongly enough my belief that we should support and promote DocBook as an open source documentation standard. It's a standard within itself, as well, meaning that it can be used universally without any one documentation project being able to control or monopolize its development. The number of documentation projects that are using DocBook is growing, and currently include KDE, GNOME, the OSWG, the LDP (partially), FreeBSD DP, and more. DocBook has begun to establish itself as a defacto standard already, simply because it is the most appropriate and powerful tool for the job at hand. The docbook site is at http://www.docbook.org Licenses. Licenses should _not_ be standardardized, nor should be attempt to do so. Each project and each author should be given the freedom to choose whatever license best suits his/her/their needs, within the scope of the project they are working on. This also means that we should not and cannot really insist that all open source documentation be enveloped into a single centralized repository. Having different licenses makes this unrealistic and very complicated. And the sheer effort that would be required for developing and maintaining such an infrastructure is immeasurable. > 4) Creating a new umbrella group is good. I don't agree with this at all. An umbrella group implies that one group is superior in a hierarchy to other groups. Developing open lines of communication and cooperation between documentation projects is good. Creating "yet another committee" is bad. I am interested in discussing the future of Open Source and Open Content documentation with all related projects. I think that these groups (and others...we should really be communicating with the FreeBSD DP and other groups about all of this) could have some incredibly interesting and enlightening discussions about these issues and more. That's why I created the Open Source Writers Group in the first place -- as a channel of communication between documentation projects. > 5) Keeping a Linux slant on things IMHO is a good thing. Keeping a Linux slant on things IMHO is a bad thing. Encouraging the development of open documentation standards through cooperation with and promotion of the LSB is a good thing for Linux. Developing and open standard for the creation of meta-information (through supporting and promotion the Open Source Research Team (OSRT)) is a good thing. Supporting DocBook as an open documentation standard is a good thing. We need to work on developing standards that everyone can work with. Ideally these standards would be supported and developed in cooperation with as many OS/OC documentation projects as possible. For Linux, these standards should be developed in cooperation with the LSB. The OSRT website can be found at http://www.metalab.unc.edu/osrt/ The rest of the ODE proposal -- involving the development of a centralized monolithic infrastructure is, in my opinion, simply unrealistic. We can achieve a great deal of good through supporting open standards and through promoting and supporting the meta-information work that the OSRT is working on. We simply cannot expect such a huge and unweildy project to ever a) be completed, and b) work. It's just too much to expect volunteers to undertake, and it's really not a good idea. Massively complex infrastructures simply have too many possible points of failure. I would be surprised (very) if such an infrastructure could be completed, nevermind used. What the open source documentation community really needs isn't more infrastrucutre or committees at this point -- what it needs, quite simply, is more people sitting down to write documentation. We have to first figure out how to get more volunteers to create more content. When the quantity of available documentation begins to outstrip our ability to effectively manage that documentation, _then_ maybe we'll need to start thinking about developing more complex and scalable infrastructures to handle it. Right now, the number of open content documents is rather pitifully small, and the quality of those documents wanders the full range from "practically unreadable" to "brilliant". We need to support open standards, including a standard method for creating meta-information. We need to figure out how to get more people writing content. We need to figure out how to improve the quality of the content produced. Etc. We have a whole host of more pressing problems that need first to be addressed. All that said, I would very much like to discuss how people think that the various open source documentation projects can work together. Again, as I mentioned once before, I created the OSWG to encourage this sort of inter-project discussion, because I do think that we can learn a great deal from one another and work together in very valuable ways. - deb -- Deb Richardson, Executive Editor Linuxcare, Inc. tel: 613.562.9723, fax: 613.562.9304 deb@linuxcare.com, http://www.linuxcare.com Linuxcare. At the Centre of Linux. From deb@mail.redhat.com Thu May 11 23:30:59 2000 Received: (qmail 17890 invoked from network); 9 Jan 2000 20:41:57 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 20:41:57 -0000 Received: from smtp.linuxcare.com (qmailr@[216.88.157.131]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id PAA07633 for ; Sun, 9 Jan 2000 15:41:56 -0500 Received: (qmail 31504 invoked from network); 9 Jan 2000 20:45:31 -0000 Received: from mg128-172.ricochet.net (HELO linuxcare.com) (deb@204.179.128.172) by smtp.linuxcare.com with SMTP; 9 Jan 2000 20:45:31 -0000 Sender: deb@mail.redhat.com Message-ID: <3878F3BA.E0B0A0EE@linuxcare.com> Date: Sun, 09 Jan 2000 15:46:50 -0500 From: Deb Richardson Organization: Linuxcare X-Mailer: Mozilla 4.51 [en] (X11; I; Linux 2.2.5-15 i686) X-Accept-Language: en MIME-Version: 1.0 To: oswg-discuss@thepuffingroup.com CC: Aaron Turner , linuxkb-discuss , oswg-discuss , gnome-doc-list , ldp-discuss , osrt , recipient@mail.redhat.com, list@mail.redhat.com, not@mail.redhat.com, shown:, ";"@mail.redhat.com Subject: Re: [oswg-dis] Re: Open Document Environment (ODE) References: Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Matthew Wilson wrote: > I agree that having one format is essential to the success of any > documentation system. However, as it seems that sgml-tools is no longer > being supported (I tried every version on my clean slackware box, and > *none* of them would compile/install/work) Perhaps we should try to move > away from SGML/DocBook, and go with XML. Although XML is still in it's > infancy, I believe that it would be an excellent platform to develop > documentation with. There is another set of tools available called "DocBook Tools". These make use of the jade dsssl engine, and are avaiable through http://sourceware.cygnus.com/docbook-tools/ . These are the tools we use for the OSWG documentation conversion scripts, and they work quite well. The default output formats could use some work, but we've got to walk before we can run ;> > XML is an open standard, heavily supported by many in the computer > industry. Even the next generation of web browsers will be able to read > it natively to some degree. It's also highly structured, designed from > the beginning to be processed into other forms. All we would need to do > is pick/create a suitable DTD. We can pick the DocBook DTD -- it supports XML as well as SGML. > As for DocBook/Linuxdoc in sgml, since the current bulk of LDP > documentation is in sgml, perhaps we would need either a conversion effort > (automated?) or a grandfathering system. What we would need is a smallish but very dedicated "strike force" of volunteers who would work to do the conversion from LinuxDoc to DocBook. Some of the conversion can be automated, but DocBook is far more verbose and powerful than LinuxDoc. As such, it really does require a human touch. It could be done...it's just a matter of finding a group of people who know DocBook and who are willing to dedicate a reasonable amount of time to working on the conversions. I, for one, would be willing to help where I can. I know that there are other people out there who would be willing to help as well. It's just a matter of organizing the team and just getting it done. - deb -- Deb Richardson, Executive Editor Linuxcare, Inc. tel: 613.562.9723, fax: 613.562.9304 deb@linuxcare.com, http://www.linuxcare.com Linuxcare. At the Centre of Linux. From gferg@hoop.timonium.sgi.com Thu May 11 23:30:59 2000 Received: (qmail 24544 invoked from network); 9 Jan 2000 20:57:56 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 20:57:56 -0000 Received: from pneumatic-tube.sgi.com (pneumatic-tube.sgi.com [204.94.214.22]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id PAA08172 for ; Sun, 9 Jan 2000 15:57:55 -0500 Received: from webster.timonium.sgi.com (webster.timonium.sgi.com [169.238.21.2]) by pneumatic-tube.sgi.com (980327.SGI.8.8.8-aspam/980310.SGI-aspam) via SMTP id MAA01597; Sun, 9 Jan 2000 12:59:02 -0800 (PST) mail_from (gferg@hoop.timonium.sgi.com) Received: from hoop.timonium.sgi.com by webster.timonium.sgi.com via ESMTP (950413.SGI.8.6.12/911001.SGI) id QAA07816; Sun, 9 Jan 2000 16:20:06 -0500 Received: by hoop.timonium.sgi.com (950413.SGI.8.6.12/940406.SGI.AUTO) id QAA11571; Sun, 9 Jan 2000 16:00:28 -0500 From: "Greg Ferguson" Message-Id: <10001091600.ZM11569@hoop.timonium.sgi.com> Date: Sun, 9 Jan 2000 16:00:27 -0500 In-Reply-To: Aaron Turner "Re: Open Document Environment (ODE)" (Jan 9, 12:01pm) References: X-Mailer: Z-Mail (3.2.3 08feb96 MediaMail) To: Aaron Turner , ldp-discuss@lists.debian.org Subject: Re: Open Document Environment (ODE) Cc: linuxkb-discuss , oswg-discuss , gnome-doc-list , osrt Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii On Jan 9, 12:01pm, Aaron Turner wrote: > Subject: Re: Open Document Environment (ODE) > On Sun, 9 Jan 2000, Greg Ferguson wrote: > > > > > Have you seen the work of the Dublin Core group, the work > > done by Debian Doc project or what has been done by Paul > > Jones and the crew at Metalab? If not, you should examine > > these documents, which describe a methodology for "resource > > discovery". We, too (SGI) are incorporating a paradigm such > > as this in the Linux documentation and products we are currently > > preparing for release: > > [snip] > > I took a quick look at the links, and I'm not sure how that would help > discovery of what applications/utilities/etc are installed on a clients > system as it doesn't seem to have any provisions for communications > between client and server, not to mention it is very documentation centric > not application centric. (Or am I missing something?) No, that's what it is meant to be...a method for discovering documentation resources. Why would you want something application centric? Or perhaps I missed something? > > > 10) I haven't ever seen SGI's bookshelf thingy or heard anything > > > about it. Maybe you could take a few screenshots for those like > > > me who have no access to SGI/Irix?? Maybe after I see it I'll sing > > > a different tune. > > > > Although a version of the system we provide does indeed scale > > down to a local system, our "main" site can be accessed with > > any old web browser from: > > > > htp://techpubs.sgi.com > > > > You can home to our Linux collection of documents from this URL: > > > > http://techpubs.sgi.com/library/tpl/cgi-bin/init.cgi?coll=linux > > Kim, is this what you're talking about when you say bookshelf? I guess > I really don't care for this. It's based too much on indexing > alphabetically, and has zero categorization by subject type. Instead > it's categorized by document type (man page, howto's, etc). We've got both method of categorization...and it's very Yahoo-like. Notice the links *below* the search box. You have End-User books, etc. Different types of content categorization can be applied, we decided to go with a paradigm we used on IRIX (Admin, End User, Developer ...those being the various bookshelfs). > Take the first entry in the Howto section for example "A mSQL and > perl Web Server Mini HOWTO". This is horribly indexed under A IMHO. Well, again, that's the straight (somewhat broken :-)) alpha index. Categorization by topic can indeed be applied, per the various "books" and "shelves". regards, -- Greg Ferguson - s/w engr / mtlhd | gferg@sgi.com SGI Tech Pubs - http://techpubs.sgi.com | 410-785-2334 Linux Doc Project - http://www.linuxdoc.org | From aturner@linuxkb.org Thu May 11 23:30:59 2000 Received: (qmail 29720 invoked from network); 9 Jan 2000 22:41:55 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 22:41:55 -0000 Received: from vodka.linuxkb.org (foobar@vodka.linuxkb.org [205.231.210.90]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id RAA13329 for ; Sun, 9 Jan 2000 17:41:55 -0500 Received: (qmail 3937 invoked by uid 10024); 9 Jan 2000 22:41:54 -0000 Date: Sun, 9 Jan 2000 14:41:54 -0800 (PST) From: Aaron Turner To: linuxkb-discuss cc: oswg-discuss@thepuffingroup.com, gnome-doc-list , ldp-discuss , osrt Subject: Re: [oswg-dis] Re: Open Document Environment (ODE) In-Reply-To: <3878F1BE.871618E4@linuxcare.com> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On Sun, 9 Jan 2000, Deb Richardson wrote: > There are a number of problems with the ODE proposal that I believe are > likely to be insurmountable. I could be wrong, but I'll outline them > here so we can discuss them. > > To be honest, I am unconvinced that creating an "umbrella group" such as > this is necessary, or even that it's a good idea. Open Source and > related projects work because they tend to not be monolithic, their > infrastructures are usually simple and make use of well-known > technologies, and there is little implication of there being a heirarchy > of people and projects. I don't think anyone is suggesting we write new standards when there already are standards for documentation markup such as Docbook and Linuxdoc. I for one would be against developing yet another documentation standard to compete for people's writing efforts. > On the other hand, I do feel that developing a set of standards for Open > Source and Open Content documentation could be extremely useful. Having > a commonly used set of standards would be very powerful. But creating a > new organization for the development and maintenence of these standards > is much more complicated (both practically and politically) than folks > might suspect. > > If we are going to work towards the development of a set of standards > for Linux documentation (which seems to be the gist of the discussion so > far -- the FreeBSD and other folks are being left out at this point), I > think we should develop these standards in cooperation with an existing > group, such as the Linux Standard Base. Personally I would be very interested in getting the Free/Open/NetBSD and other groups involved in such a project. I however also feel (rather strongly) that content should be compartimentalized so that when I'm looking for getting Apache to run on Linux I don't keep running into FreeBSD centeric docs. Of course these compartments can overlap, but we need to be able to split it up for the end user. > The LSB website can be found at http://www.linuxbase.org. > > The LSB is an orgazation working to develop and promote a set of > standards that will increase compatibility among Linux distributions > that will enable software applications to install and run on any > compliant Linux system. The LSB is already being supported by a large > number of companies and organizations, including Linuxcare, Corel, the > Debian Project, TurboLinux, VA Linux, SGI, Software in the Public > Interest, Red Hat, and more. Wouldn't using the LSB or LDP exclude the FreeBSD'ers as those are Linux specific organization? I'm confused about the relationships between the various groups as you propose. > Are documentation standards within the current scope of the LSB? Not > that I know of. But I cannot imagine that the LSB would be unwilling to > examine a proposal and work with us to develop and promote whatever > standards we devise. I would assume so as well. > As for the development of standardized tools -- well, this is definitely > outside the scope of the LSB. It is also a very non-open-source idea -- > one of the beautiful things about Open Source is that it provides a user > with choice -- a choice of distributions, of packages, of licenses, of > programs, etc. As long as you have an open standard, others can write tools for it. HTML is such an example. > We don't need a standardized tools if we have an open documentation > standard that is supported and promoted by the majority of Open > Source/Linux documentation projects. One standard, used as the basis of > even hundreds of different tools, is good enough. As long as the tools > are compliant with the standard, that is. People will be able to choose > from among these tools to find those which best suit their own needs, > systems, and work preferences. For me at least, I've always been interested in a system where the content and retrevial engine are very integrated. It still can and should be open, but such a system has many benifits for the end user. Realize that I'm not talking about so much about the markup of the document, but rather the storage and retrieval of the document itself. > The idea of a "bookshelf" is a bit shortsighted. The majority of Open > Source docs are delivered and used in electronic formats. The whole > idea of a "book" is somewhat antiquated in the face of these electronic > formats. Also, if you look around, the Open Source documentation > community (the volunteer writers, editors, etc) have produced few large > works. Most of the documents we have are short -- HOWTOs, MiniHOWTOs, > FAQs, etc. There's a reason for this -- writing documentation is hard. > Writing short, focused, procedural-style documents is simply easier than > writing a book. It takes a great deal of time, dedication, and bloody > hard work to produce a book. You're going to find precious few people > who are going to volunteer their time to do so. I'd have to agree with this analysis. > So, why not have a bunch of volunteers collaborate on a single > monolithic work? It's more likely that such a project would be > successful, but there's still a lot of work that goes into developing, > coordinating, and maintaining such a project. And the result is still a > "book" which, as I've mentioned, is a bit limited given the power and > flexibility of electronic formats. Agreed. > I do _strongly_ support the idea of using DocBook as a document format > standard. Aaron mentioned that having to do short docs using DocBook > would be a bit of a pain. That's true. Using DocBook to markup long > docs is a bit of a pain, to be honest. But the results are worth the > effort. SGML is a very very powerful tool. Used properly it can make > cross-referencing, indexing, and other stuff happen as if by magic. I > cannot express strongly enough my belief that we should support and > promote DocBook as an open source documentation standard. It's a > standard within itself, as well, meaning that it can be used universally > without any one documentation project being able to control or > monopolize its development. The number of documentation projects that > are using DocBook is growing, and currently include KDE, GNOME, the > OSWG, the LDP (partially), FreeBSD DP, and more. DocBook has begun to > establish itself as a defacto standard already, simply because it is the > most appropriate and powerful tool for the job at hand. Not being a Docbook expert myself (Santa got me the book, but I've yet to open it) I don't have much to say except your thoughts seem to agree with many others I've heard. I would assume though that it would be quite possible for someone to develop a web form or the like that the writer can fill out to create a DocBook compliant article for the small stuff. > The docbook site is at http://www.docbook.org > > Licenses. Licenses should _not_ be standardardized, nor should be > attempt to do so. Each project and each author should be given the > freedom to choose whatever license best suits his/her/their needs, > within the scope of the project they are working on. I've seen situations where the author chose not to pick a good license and it ended up causing a lot of problems. Many authors IMHO wrongly believe that they need to maintain full control over their work, which almost always ends up causing the doc to fail to be properly maintained. The LDP is full of these examples and there are many other. A few people wise up to this (The Linux Admin. Security Guide is one such example) but it would be better to avoid it in the first place. Sometimes no information is better than bad/outdated info. Also lack of standardized licenses prevents a centralized repository which is desperately needed. You can't expect end users to look at 20 different sites looking for one answer just because some dufus couldn't pick a good license. > This also means that we should not and cannot really insist that all > open source documentation be enveloped into a single centralized > repository. Having different licenses makes this unrealistic and very > complicated. And the sheer effort that would be required for developing > and maintaining such an infrastructure is immeasurable. Well I would definately have to disagree there. I know personally how complicated such an infrastructure can be, and I'm happy to say it is very doable. My group, the Linux KB Project has been working on this for the past 14 months. While I'll be the first to admit that we're nowhere close to where I had hoped we would be after 14 months of work, I am very happy with where the project is headed and how things are developing. As it turns out, the biggest problem hasn't been technical or getting enough computing/bandwidth resources to pull it off- it's been building a team who is motivated enough to do it. Good coders tend to have little time, and vice-versa. Patience is key as I am learning first hand. Look for the Linux KB Project's source code and SQL schema to be made availble in the next few weeks. > > 4) Creating a new umbrella group is good. > > I don't agree with this at all. An umbrella group implies that one > group is superior in a hierarchy to other groups. Developing open lines > of communication and cooperation between documentation projects is > good. Creating "yet another committee" is bad. I guess I don't know how to do the standardization required to pull this off without creating a dedicated oversight committee to manage it. All these groups have different opinions and needs relating to documentation. Some groups are far more interested in the markup than the retrieval. I don't think a loose-nit group can create the needed colaboration required to make it sucessful. There's a lot more to documentation than writing- people need to find it first before they can read it. > I am interested in discussing the future of Open Source and Open Content > documentation with all related projects. I think that these groups (and > others...we should really be communicating with the FreeBSD DP and other > groups about all of this) could have some incredibly interesting and > enlightening discussions about these issues and more. That's why I > created the Open Source Writers Group in the first place -- as a channel > of communication between documentation projects. > > > 5) Keeping a Linux slant on things IMHO is a good thing. > > Keeping a Linux slant on things IMHO is a bad thing. Encouraging the > development of open documentation standards through cooperation with and > promotion of the LSB is a good thing for Linux. Developing and open > standard for the creation of meta-information (through supporting and > promotion the Open Source Research Team (OSRT)) is a good thing. > Supporting DocBook as an open documentation standard is a good thing. > We need to work on developing standards that everyone can work with. > Ideally these standards would be supported and developed in cooperation > with as many OS/OC documentation projects as possible. For Linux, these > standards should be developed in cooperation with the LSB. Again I'm confused about being anti-Linux slanted and yet using the LSB. > The OSRT website can be found at http://www.metalab.unc.edu/osrt/ > > The rest of the ODE proposal -- involving the development of a > centralized monolithic infrastructure is, in my opinion, simply > unrealistic. We can achieve a great deal of good through supporting > open standards and through promoting and supporting the meta-information > work that the OSRT is working on. We simply cannot expect such a huge > and unweildy project to ever a) be completed, and b) work. It's just > too much to expect volunteers to undertake, and it's really not a good > idea. Massively complex infrastructures simply have too many possible > points of failure. I would be surprised (very) if such an > infrastructure could be completed, nevermind used. That's one reason why I'm against a distributed system. You can build such a system in a monolithic manner. Making it distributed is significantly more complicated. But once you've got something to show off and people realize it's power, you can start thinking bigger, because people get motivated to help. Seriously, the Linux kernel and the GNU tools are FAR more ambitious than even a distributed documentation retervial engine. > What the open source documentation community really needs isn't more > infrastrucutre or committees at this point -- what it needs, quite > simply, is more people sitting down to write documentation. We have to > first figure out how to get more volunteers to create more content. > When the quantity of available documentation begins to outstrip our > ability to effectively manage that documentation, _then_ maybe we'll > need to start thinking about developing more complex and scalable > infrastructures to handle it. Right now, the number of open content > documents is rather pitifully small, and the quality of those documents > wanders the full range from "practically unreadable" to "brilliant". It's already unmanageable- do a search on Yahoo for some linux related question- "Linux pop3 server" returns 13,000+ hits. You may say they should go someplace else for an answer, but right now there isn't a place for one stop shopping for Linux documentation on the web. It takes me forever sometime to find what I'm looking for and I end up on a maillist asking the same question someone else did last week because I can't find the list archives. There really is a lot docs written by some Joe that he put on his web site that most people never find because they don't know where to look. At the same time, I couldn't agree more that we need more authors writing good documentation. > We need to support open standards, including a standard method for > creating meta-information. We need to figure out how to get more people > writing content. We need to figure out how to improve the quality of > the content produced. Etc. Agreed. > We have a whole host of more pressing problems that need first to be > addressed. Perhaps you're right. Problem is that I'm not interested in doing that. :) I'm far more interested in building an infrastructure to allow people to find documentation that other people write regardless of its origin than actually writing docs myself. You may not agree with that, but I think it is in your and everyone's best interest to work with people like me because I fill a vaild need within the community. > All that said, I would very much like to discuss how people think that > the various open source documentation projects can work together. > Again, as I mentioned once before, I created the OSWG to encourage this > sort of inter-project discussion, because I do think that we can learn a > great deal from one another and work together in very valuable ways. Sounds good. I haven't been able to get a hold of Roger with SEUL yet, so someone PLEASE setup a list for this! Everytime someone responds to one of my emails I get 3 copies and it's driving me nuts! -- Aaron Turner, Core Developer http://vodka.linuxkb.org/~aturner/ Linux Knowledge Base Organization http://linuxkb.org/ Because world domination requires quality open documentation. aka: aturner@vicinity.com, aturner@pobox.com, ion_beam_head@ashtech.net The difference between `Unstable' and `Usable' is only two characters: NT From deb@mail.redhat.com Thu May 11 23:30:59 2000 Received: (qmail 2713 invoked from network); 9 Jan 2000 22:53:22 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 9 Jan 2000 22:53:22 -0000 Received: from smtp.linuxcare.com (qmailr@[216.88.157.131]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id RAA14027 for ; Sun, 9 Jan 2000 17:53:22 -0500 Received: (qmail 7440 invoked from network); 9 Jan 2000 22:56:53 -0000 Received: from mg128-172.ricochet.net (HELO linuxcare.com) (deb@204.179.128.172) by smtp.linuxcare.com with SMTP; 9 Jan 2000 22:56:53 -0000 Sender: deb@mail.redhat.com Message-ID: <3879128B.807A3789@linuxcare.com> Date: Sun, 09 Jan 2000 17:58:19 -0500 From: Deb Richardson Organization: Linuxcare X-Mailer: Mozilla 4.51 [en] (X11; I; Linux 2.2.5-15 i686) X-Accept-Language: en MIME-Version: 1.0 To: Aaron Turner CC: linuxkb-discuss , oswg-discuss@thepuffingroup.com, gnome-doc-list , ldp-discuss , osrt Subject: Re: [oswg-dis] Re: Open Document Environment (ODE) References: Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Aaron Turner wrote: > Sounds good. I haven't been able to get a hold of Roger with SEUL yet, so > someone PLEASE setup a list for this! Everytime someone responds to one > of my emails I get 3 copies and it's driving me nuts! If it's okay with everyone, I'll have one set up through the oswg within the next couple of hours. For sake of simplicity, I'll call it "ode-discuss@oswg.org". It doesn't need to be a permanent list, just a temporary solution until we decide how this should be approached. I, for one, am extremely excited about the discussions that have been going on here. I recommend that we approach and involve the *BSD documentation projects and others when we migrate discussion to the new list. If anyone knows of other projects we should approach about involvement, send a note and/or tell them about the new list when it's set up. I'll send a notification when the list is ready. Right now I have to go get food :> I'll respond to Aaron's post in more detail later this evening. - deb -- Deb Richardson, Executive Editor Linuxcare, Inc. tel: 613.562.9723, fax: 613.562.9304 deb@linuxcare.com, http://www.linuxcare.com Linuxcare. At the Centre of Linux. From deb@mail.redhat.com Thu May 11 23:30:59 2000 Received: (qmail 225 invoked from network); 10 Jan 2000 01:35:53 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 10 Jan 2000 01:35:53 -0000 Received: from smtp.linuxcare.com (qmailr@[216.88.157.131]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id UAA19482 for ; Sun, 9 Jan 2000 20:35:53 -0500 Received: (qmail 20128 invoked from network); 10 Jan 2000 01:39:16 -0000 Received: from mg134-219.ricochet.net (HELO linuxcare.com) (deb@204.179.134.219) by smtp.linuxcare.com with SMTP; 10 Jan 2000 01:39:16 -0000 Sender: deb@mail.redhat.com Message-ID: <387938A1.6ACE66ED@linuxcare.com> Date: Sun, 09 Jan 2000 20:40:49 -0500 From: Deb Richardson Organization: Linuxcare X-Mailer: Mozilla 4.51 [en] (X11; I; Linux 2.2.5-15 i686) X-Accept-Language: en MIME-Version: 1.0 To: oswg-discuss@oswg.org, ldp-discuss@lists.linuxdoc.org, osrt@metalab.unc.edu, linuxkb-discuss@seul.org, ode-discuss@oswg.org, gnome-doc-list@gnome.org Subject: ode-discuss archives Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit The new mailing list will be archived via hypermail, and the archives are available at: http://www.oswg.org/archives/ode-discuss/ As I mentioned before, this list can be considered a temporary solution to the mail flood this discussion has brought for some of us (I get at least 3 copies of each mail that's cc'd). Under no circumstances do I want this to be mis-read as an attempt by the OSWG to co-opt these discussions, and the list can be dissolved at any time. Again, to subscribe, send mail to: ode-discuss-request@oswg.org with "subscribe" in the subject line. To post to the new list, send mail to ode-discuss@oswg.org. If you know of other Open Source or Open Content documentation projects that might be interested in taking part in these discussions, please forward this information along to them. In particular, I think that the FreeBSD Documentation Project and the KDE documentation project should be included. I'll send mail to those lists when I find the appropriate addresses. - deb -- Deb Richardson, Executive Editor Linuxcare, Inc. tel: 613.562.9723, fax: 613.562.9304 deb@linuxcare.com, http://www.linuxcare.com Linuxcare. At the Centre of Linux. From mok@imsb.au.dk Thu May 11 23:30:59 2000 Received: (qmail 5309 invoked from network); 10 Jan 2000 17:48:57 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 10 Jan 2000 17:48:57 -0000 Received: from origo.imsb.au.dk (root@origo.imsb.au.dk [192.38.35.2]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA24665 for ; Mon, 10 Jan 2000 12:48:56 -0500 Received: from origo.imsb.au.dk (IDENT:mok@origo.imsb.au.dk [192.38.35.2]) by origo.imsb.au.dk (8.9.3/8.9.3) with ESMTP id SAA12964; Mon, 10 Jan 2000 18:56:29 +0100 Date: Mon, 10 Jan 2000 18:56:28 +0100 (CET) From: Morten Kjeldgaard To: Kim Lester cc: ldp-discuss@lists.debian.org, gnome-doc-list@gnome.org, recipient list not shown: ; Subject: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure] In-Reply-To: <387627B0.5C0890AF@dfusion.com.au> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On Fri, 7 Jan 2000, Kim Lester wrote: > >From what I've seen LDP and GDP are addressing an important part of > getting a set of new docs up-to-date > and mostly in some sort of format. What I see as the next step is > unifying the strucutre. A few months ago, I tried raising this discussion on the ldp-discuss mailing list, but noone picked up the thread. I guess I didn't express myself clearly enough. I propose that the distinction between HOWTOs and mini-HOWTOs should be abolished, because a grouping based on the sizes of the documents it is a very arbitrary and non-intuitive distinction. In fact, some mini-HOWTOs are longer than some HOWTOs. Approximately 2/3 of the mini-HOWTOs are longer than the shortest HOWTOs! Historically, HOWTOs were in LinuxDoc (SGML) format, and mini-HOWTOs were not. But now, all mini-HOWTOs are also in LinuxDoc format. A new way of grouping the documentation should be implemented, to make it faster and easier to locate the document you need. I very much support Kim's ideas: > The hierarchy should be able to be cross refrernced in at least 3 ways > (and also via > a word search): > By title > By problem/concept/ > By program|module|group name (not more than 3 levels deep, please! :-)) /Morten -- Morten Kjeldgaard | Phone : +45 89 42 50 26 Institute of Molecular and Structural Biology | Fax : +45 86 12 31 78 Aarhus University | Home : +45 86 18 81 80 Gustav Wieds Vej 10 C, DK-8000 Aarhus C, Denmark | icq : 27224900 From mok@imsb.au.dk Thu May 11 23:30:59 2000 Received: (qmail 19484 invoked from network); 10 Jan 2000 18:07:39 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 10 Jan 2000 18:07:39 -0000 Received: from origo.imsb.au.dk (root@origo.imsb.au.dk [192.38.35.2]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA26071 for ; Mon, 10 Jan 2000 13:07:38 -0500 Received: from origo.imsb.au.dk (IDENT:mok@origo.imsb.au.dk [192.38.35.2]) by origo.imsb.au.dk (8.9.3/8.9.3) with ESMTP id TAA13466; Mon, 10 Jan 2000 19:15:14 +0100 Date: Mon, 10 Jan 2000 19:15:13 +0100 (CET) From: Morten Kjeldgaard To: Kim Lester cc: ldp-discuss@lists.debian.org, gnome-doc-list@gnome.org, recipient list not shown: ;, recipient list not shown: ; Subject: Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure] In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On Mon, 10 Jan 2000, Morten Kjeldgaard wrote: > A new way of grouping the documentation should be implemented, to make it > faster and easier to locate the document you need. I very much support > Kim's ideas: > > > The hierarchy should be able to be cross refrernced in at least 3 ways > > (and also via > > a word search): > > By title > > By problem/concept/ > > By program|module|group name Technically, the grouping and other information of each document could easily be encoded in an SGML comment near the beginning of the file for example: These instructions could be used by a script to build the documentation hierachy in whatever way desired. It should be the responsibility of the LDP to coordinate with the authors the assignment of group, keywords etc. /Morten -- Morten Kjeldgaard | Phone : +45 89 42 50 26 Institute of Molecular and Structural Biology | Fax : +45 86 12 31 78 Aarhus University | Home : +45 86 18 81 80 Gustav Wieds Vej 10 C, DK-8000 Aarhus C, Denmark | icq : 27224900 From d-mueth@uchicago.edu Thu May 11 23:30:59 2000 Received: (qmail 4726 invoked from network); 10 Jan 2000 19:12:25 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 10 Jan 2000 19:12:25 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA30752 for ; Mon, 10 Jan 2000 14:12:24 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id NAA00878; Mon, 10 Jan 2000 13:12:16 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Mon, 10 Jan 2000 13:12:15 -0600 (CST) From: Dan Mueth X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org cc: Dan Mueth , "FALLON,DAVID JOSEPH" , "David C. Mason" Subject: Announcing GNOME Documentation Status Table (Beta) Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII We would like to announce the beta of the GNOME Documentation Status Table: http://www.gnome.org/gdp/doctable A detailed description of this site is provided below. We invite GDP members to try out this site and provide feedback. The basic functionality of this site should be reliable and users are invited to begin using it immediately. We would like everyone who is writing application documentation to use this site to indicate what thich application(s) they are writing documentation for. We would also like application developers to volunteer to be contacts that documentation authors can ask technical questions to. This can be done directly through the site or by emailing the information to doctable@rheo.uchicago.edu. For full functionality, users must log in with password. To request a login, send an email to doctable@rheo.uchicago.edu including your email address and desired login name and password. Please note that in addition to the gnome-doc mailing list, suggestions may be included directly in the table in the Comments section for the "doctable" entry at the bottom of the "Additional Applications" section. Dan and David d-mueth@uchicago.edu dfallon@ucla.edu -------- The initial objectives of the GNOME Documentation Status Table are to track the status of all GNOME application documentation, to track which authors are writing documentation for each application, and to provide a discussion forum specific to each application. This web page will serve as a focal point for application documentation efforts, providing basic instructions and links to help new authors get started, basic guidelines on what (most) applications' documentation should consist of, and the application documentation status table. This table provides the following features: Anonymous users: 1) can suggest new applications to be added to the table 2) can add anonymous comments for a particular application Login users: 1) can add new applications to the table 2) can moderate anonymously suggested applications 3) can add comments and TODO items for each application 4) can delete comments and TODO items 5) can edit or remove applications in the table We are in the process of expanding the scope beyond application documentation to include other documentation, such as non-application GNOME documentation (the user and developer docs) and possibly translations. From ningersoll@mail.codenet.net Thu May 11 23:30:59 2000 Received: (qmail 26294 invoked from network); 10 Jan 2000 19:34:48 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 10 Jan 2000 19:34:48 -0000 Received: from mail.codenet.net (codenet.net [209.136.121.8]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA32499 for ; Mon, 10 Jan 2000 14:34:48 -0500 Date: Mon, 10 Jan 2000 12:38:05 -0700 Message-Id: <200001101238.AA695730722@mail.codenet.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii From: "Nelson_Ingersoll" Reply-To: To: Kim Lester , Morten Kjeldgaard CC: , , "recipient@mail.codenet.net list not shown": ;, "recipient@mail.codenet.net list not shown": ; Subject: Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure] X-Mailer: Morten, I agree that the now artificial segregation of HOWTOs and mini-HOWTOs should be abolished. I also like your suggestions about the indexing/grouping of the HOWTOs. - Nelson Ingersoll ---------- Original Message ---------------------------------- From: Morten Kjeldgaard Date: Mon, 10 Jan 2000 19:15:13 +0100 (CET) >On Mon, 10 Jan 2000, Morten Kjeldgaard wrote: > >> A new way of grouping the documentation should be implemented, to make it >> faster and easier to locate the document you need. I very much support >> Kim's ideas: >> >> > The hierarchy should be able to be cross refrernced in at least 3 ways >> > (and also via >> > a word search): >> > By title >> > By problem/concept/ >> > By program|module|group name > >Technically, the grouping and other information of each document could >easily be encoded in an SGML comment near the beginning of the file for >example: > > > > >These instructions could be used by a script to build the documentation >hierachy in whatever way desired. It should be the responsibility of the >LDP to coordinate with the authors the assignment of group, keywords etc. > >/Morten > >-- >Morten Kjeldgaard | Phone : +45 89 42 50 26 >Institute of Molecular and Structural Biology | Fax : +45 86 12 31 78 >Aarhus University | Home : +45 86 18 81 80 >Gustav Wieds Vej 10 C, DK-8000 Aarhus C, Denmark | icq : 27224900 > > >-- >To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org >with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org > > From guylhem@metalab.unc.edu Thu May 11 23:30:59 2000 Received: (qmail 20053 invoked from network); 11 Jan 2000 09:28:19 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 11 Jan 2000 09:28:19 -0000 Received: from guylhem.free.fr (mail@toulouse-51-204.dial.proxad.net [212.27.51.204]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id EAA16827 for ; Tue, 11 Jan 2000 04:28:18 -0500 Received: from guylhem by guylhem.free.fr with local (Exim 3.02 #3) id 127p0t-0000LZ-00; Tue, 11 Jan 2000 01:18:19 +0100 Date: Tue, 11 Jan 2000 01:18:19 +0100 From: Guylhem Aznar To: Morten Kjeldgaard Cc: Kim Lester , ldp-discuss@lists.debian.org, gnome-doc-list@gnome.org, recipient list not shown: ; Subject: Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure] Message-ID: <20000111011819.A1334@guylhem.free.fr> References: <387627B0.5C0890AF@dfusion.com.au> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: ; from mok@imsb.au.dk on Mon, Jan 10, 2000 at 06:56:28PM +0100 X-Newsreader: Microsoft Outlook Express 5.00.2314.1300 X-MimeOLE: Produced By Microsoft MimeOLE V5.00.2314.1300 On Mon, Jan 10, 2000 at 06:56:28PM +0100, Morten Kjeldgaard wrote: > I propose that the distinction between HOWTOs and mini-HOWTOs should be > abolished, because a grouping based on the sizes of the documents it is a > very arbitrary and non-intuitive distinction. In fact, some mini-HOWTOs > are longer than some HOWTOs. Approximately 2/3 of the mini-HOWTOs are > longer than the shortest HOWTOs! Aboloshing the distrinction is a good idea, but it would confuse people. mini HOWTOs are "mini" since they focus on a specific topic -- Guylhem Aznar, Linux Documentation Project: http://www.linuxdoc.org ------>>> Attention, my new email is guylhem \@/ metalab.unc.edu "They who can give up essential liberty to purchase a little temporary safety, deserve neither liberty nor safety." - Benjamin Franklin From hobbit@aloss.ukuu.org.uk Thu May 11 23:30:59 2000 Received: (qmail 3015 invoked from network); 11 Jan 2000 14:33:35 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 11 Jan 2000 14:33:35 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id JAA28588 for ; Tue, 11 Jan 2000 09:33:32 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id OAA29017 for gnome-doc-list@gnome.org; Tue, 11 Jan 2000 14:33:26 GMT Date: Tue, 11 Jan 2000 14:33:25 +0000 From: Telsa Gwynne To: gnome-doc-list@gnome.org Subject: gtop docs and various questions Message-ID: <20000111143325.A28848@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i I have sent this to Martin, the gtop maintainer, already, but if anyone wants a look, the getting-somewhere version, after Sasha's sanity checking and a friend's technical checking, is at http://roadrunner.swansea.linux.org.uk/~hobbit/gtopindex.html ...and its associated links, and a tarball of the Docbook is at http://roadrunner.swansea.linux.org.uk/~hobbit/gtopdraft.sgml.gz I have a to-do list and some questions of course :) Anyone who can explain exactly what the views of shared, virtual and total memory are showing, please tell me! Someone I asked said that one of these isn't actually calculated by Linux: is it a BSD thing, then, and if so, what's getting shown when I look at it on Linux? Does it make sense to people who don't know much about it? So far, the people who have seen it have mostly been people who understand this stuff, and although they say it's clear, I don't know whether it's clear to new folks. I had a frenzy of adding tags. I -hope- they're the right ones. What else can I mark up? :) This is fun! It may need more pictures. I'm not sure on that. This is partly because pngs turn out to be way bigger than jpgs. Also, my pngs display fine in xv and in Netscape, but the gnome-help-browser shows them as very blotchy. (The pictures aren't in that directory yet because I'm a bit worried about the effect on the modem. :) They're simply what the titles would lead you to expect.) Finally, some gnome-documentation-specific questions. Should it be GNOME or Gnome? GNOME is cumbersome and breaks the flow to read it. This is very noticeable when I printed it out. However, I suspect it's probably the 'proper' way, and most of the rest of the docs seem to use that. UNIX, Unix, unix, or *nix-like? Are there preferred terms for different concepts? Menubar (like programmers write it) or menu-bar (more user- friendly?). Toolbar or tool-bar? I got the stuff off Dave Mason's "Using the GNOME PNG Support Custom DTD and Stylesheets" page at http://www.labs.redhat.com/png/custom.html and installed it. This worked fine for including pngs, and worked fine for generating the html (although Dave, you need directions about what you use instead of 'db2html' on the web page as well as inside the stylesheets! Really, I missed that completely at first!). When I tried to generate a printable result with the gnome-print.dsl one, though, the commandline from the stylesheet comments didn't work, and I spent a lot of time faffing about before simply removing the pngs, altering the DTD declaration (I think: the bit at the top of the file :)) back to plain docbook, and running db2ps. That worked fine. Trying the commands that db2ps actually runs, one at a time, on the Gnome-png-Docbook variety just didn't work, and I spent ages trying. Sasha suggested that what 90% of people are going to want to know first is "how to find and kill rogue processes" and that I should put an appendix with an obvious link in, or a "go here if all you want to do is find how to kill things". Yes? No? He also suggested moving the menus sections from each page (processes, memory and filesystems) into their own section or otherwise cutting down on duplication. I think they're in the right place, but I'm open to persuasion. They could go next to the preferences stuff, I suppose. I know it's detailed, but there is no one place where you can get all this information normally. When you put it all together, there's a lot. I have, I hope, tried to put the complicated bits at the end of each paragraph/section, so people can skim when it gets hard! I think that's it. Feedback welcome :) Telsa From gleblanc@mail4.aracnet.com Thu May 11 23:30:59 2000 Received: (qmail 24089 invoked from network); 11 Jan 2000 14:56:48 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 11 Jan 2000 14:56:48 -0000 Received: from mail4.aracnet.com (root@mail4.aracnet.com [216.99.193.36]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id JAA30071 for ; Tue, 11 Jan 2000 09:56:47 -0500 Received: from cu-portland.edu (216-99-218-48.dsl.aracnet.com [216.99.218.48]) by mail4.aracnet.com (8.9.3/8.9.3) with ESMTP id GAA23139; Tue, 11 Jan 2000 06:56:42 -0800 Sender: gleblanc@mail4.aracnet.com Message-ID: <387B44A6.1F788BB7@cu-portland.edu> Date: Tue, 11 Jan 2000 06:56:38 -0800 From: Gregory Leblanc X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.14 i586) X-Accept-Language: en MIME-Version: 1.0 To: Guylhem Aznar CC: ldp-discuss@lists.debian.org, gnome-doc-list@gnome.org Subject: Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure] References: <387627B0.5C0890AF@dfusion.com.au> <20000111011819.A1334@guylhem.free.fr> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Guylhem Aznar wrote: > > On Mon, Jan 10, 2000 at 06:56:28PM +0100, Morten Kjeldgaard wrote: > > I propose that the distinction between HOWTOs and mini-HOWTOs should be > > abolished, because a grouping based on the sizes of the documents it is a > > very arbitrary and non-intuitive distinction. In fact, some mini-HOWTOs > > are longer than some HOWTOs. Approximately 2/3 of the mini-HOWTOs are > > longer than the shortest HOWTOs! > > Aboloshing the distrinction is a good idea, but it would confuse people. > > mini HOWTOs are "mini" since they focus on a specific topic There are two ways of looking at this, the first is to say let's just get rid of the mini-HOWTOs and integrate them with the rest of the documents. The other option (it seems to me) is to make the distinction clearer. This would require that authors guide, with a set of criteria for each type of document. The mini-HOWTOs aren't always specific as they stand right now. Enough ranting from me, it's before 7 AM and I'm not capable of writing english this early, Greg From kirillov@math.sunysb.edu Thu May 11 23:30:59 2000 Received: (qmail 21432 invoked from network); 11 Jan 2000 17:37:40 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 11 Jan 2000 17:37:40 -0000 Received: from peconic.math.sunysb.edu (mail.math.sunysb.edu [129.49.18.67]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA09322 for ; Tue, 11 Jan 2000 12:37:39 -0500 Received: from copiague.math.sunysb.edu (IDENT:root@copiague [129.49.18.192]) by peconic.math.sunysb.edu (8.9.3/8.9.3) with ESMTP id MAA26504 for ; Tue, 11 Jan 2000 12:37:39 -0500 (EST) Received: (from kirillov@localhost) by copiague.math.sunysb.edu (8.9.3/8.9.3) id MAA17622 for gnome-doc-list@gnome.org; Tue, 11 Jan 2000 12:42:55 -0500 Date: Tue, 11 Jan 2000 12:42:54 -0500 From: Alexander Kirillov To: gnome-doc-list@gnome.org Subject: Re: gtop docs and various questions Message-ID: <20000111124254.A17610@math.sunysb.edu> References: <20000111143325.A28848@aloss.ukuu.org.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <20000111143325.A28848@aloss.ukuu.org.uk>; from hobbit@aloss.ukuu.org.uk on Tue, Jan 11, 2000 at 02:33:25PM +0000 > Finally, some gnome-documentation-specific questions. Should > it be GNOME or Gnome? GNOME is cumbersome and breaks the flow > to read it. This is very noticeable when I printed it out. > However, I suspect it's probably the 'proper' way, and most > of the rest of the docs seem to use that. UNIX, Unix, unix, > or *nix-like? Are there preferred terms for different concepts? > Menubar (like programmers write it) or menu-bar (more user- > friendly?). Toolbar or tool-bar? > > Telsa > I'd vote for GNOME, UNIX, menubar and toolbar, thouhg could also live with Unix. Sasha From hp@icon.labs.redhat.com Thu May 11 23:30:59 2000 Received: (qmail 25020 invoked from network); 11 Jan 2000 18:43:40 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 11 Jan 2000 18:43:39 -0000 Received: from icon.labs.redhat.com (root@icon.labs.redhat.com [207.175.42.144]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA15882 for ; Tue, 11 Jan 2000 13:43:39 -0500 Received: (from hp@localhost) by icon.labs.redhat.com (8.9.3/8.9.3) id NAA16890; Tue, 11 Jan 2000 13:40:42 -0500 X-Authentication-Warning: icon.labs.redhat.com: hp set sender to hp@redhat.com using -f Sender: hp@icon.labs.redhat.com To: Alexander Kirillov Cc: gnome-doc-list@gnome.org Subject: Re: gtop docs and various questions References: <20000111143325.A28848@aloss.ukuu.org.uk> <20000111124254.A17610@math.sunysb.edu> From: Havoc Pennington Date: 11 Jan 2000 13:40:41 -0500 In-Reply-To: Alexander Kirillov's message of "Tue, 11 Jan 2000 12:42:54 -0500" Message-ID: Lines: 9 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Alexander Kirillov writes: > I'd vote for GNOME, UNIX, menubar and toolbar, thouhg could also live > with Unix. > UNIX the trademark is officially supposed to be in all-caps; GNOME is also "officially" (hah) in all caps. Havoc From guylhem@metalab.unc.edu Thu May 11 23:30:59 2000 Received: (qmail 15468 invoked from network); 12 Jan 2000 00:41:26 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 00:41:26 -0000 Received: from guylhem.free.fr (mail@toulouse-50-36.dial.proxad.net [212.27.50.36]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id TAA15875 for ; Tue, 11 Jan 2000 19:41:24 -0500 Received: from guylhem by guylhem.free.fr with local (Exim 3.02 #6) id 128BEu-0000iR-00; Wed, 12 Jan 2000 01:02:16 +0100 Date: Wed, 12 Jan 2000 01:02:16 +0100 From: Guylhem Aznar To: Gregory Leblanc Cc: Guylhem Aznar , ldp-discuss@lists.debian.org, gnome-doc-list@gnome.org Subject: Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure] Message-ID: <20000112010216.C2700@guylhem.free.fr> References: <387627B0.5C0890AF@dfusion.com.au> <20000111011819.A1334@guylhem.free.fr> <387B44A6.1F788BB7@cu-portland.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <387B44A6.1F788BB7@cu-portland.edu>; from gleblanc@cu-portland.edu on Tue, Jan 11, 2000 at 06:56:38AM -0800 X-Newsreader: Microsoft Outlook Express 5.00.2314.1300 X-MimeOLE: Produced By Microsoft MimeOLE V5.00.2314.1300 On Tue, Jan 11, 2000 at 06:56:38AM -0800, Gregory Leblanc wrote: > There are two ways of looking at this, the first is to say let's just > get rid of the mini-HOWTOs and integrate them with the rest of the > documents. The other option (it seems to me) is to make the distinction Quick poll : who would like this? > they stand right now. Enough ranting from me, it's before 7 AM and I'm > not capable of writing english this early, What's your mother tongue? (just curious to know) -- Guylhem Aznar, Linux Documentation Project: http://www.linuxdoc.org ------>>> Attention, my new email is guylhem \@/ metalab.unc.edu "They who can give up essential liberty to purchase a little temporary safety, deserve neither liberty nor safety." - Benjamin Franklin From kim@new-smtp1.ihug.com.au Thu May 11 23:30:59 2000 Received: (qmail 29518 invoked from network); 12 Jan 2000 01:24:49 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 01:24:49 -0000 Received: from new-smtp1.ihug.com.au (root@new-smtp1.ihug.com.au [203.109.250.27]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id UAA18004 for ; Tue, 11 Jan 2000 20:24:44 -0500 Received: from dfusion.com.au (IDENT:kim@p55-max10.syd.ihug.com.au [206.17.105.183]) by new-smtp1.ihug.com.au (8.9.3/8.9.3) with ESMTP id MAA04256; Wed, 12 Jan 2000 12:23:48 +1100 Sender: kim@new-smtp1.ihug.com.au Message-ID: <387BD751.13BCF1F8@dfusion.com.au> Date: Wed, 12 Jan 2000 01:22:25 +0000 From: Kim Lester Organization: Datafusion Systems Pty Ltd X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.3.35 i686) X-Accept-Language: en MIME-Version: 1.0 To: Guylhem Aznar CC: Morten Kjeldgaard , ldp-discuss@lists.debian.org, gnome-doc-list@gnome.org, ode-discuss@oswg.org Subject: Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure] References: <387627B0.5C0890AF@dfusion.com.au> <20000111011819.A1334@guylhem.free.fr> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Guylhem Aznar wrote: > > On Mon, Jan 10, 2000 at 06:56:28PM +0100, Morten Kjeldgaard wrote: > > I propose that the distinction between HOWTOs and mini-HOWTOs should be > > abolished, because a grouping based on the sizes of the documents it is a [... snip ...] > Aboloshing the distrinction is a good idea, but it would confuse people. > mini HOWTOs are "mini" since they focus on a specific topic IMHO removing the distincition it won't confuse anyone. How is IP-Masquerade (mini) more specific thatn IPX-Howto (HOWTO). Similarly Assembler is probably less important to many than LILO etc. Whilst I see the original purpose of HOWTOs vs minis (which isn't bad) the line has long since blurred. It is now more a matter of personal perspective. One thing you could do is something like stick to a single dir and use a stricter naming scheme. Eg: Networking might be the main (overview) howto and if someone has an IP specific topic it could be named: "Networking-IP-Masquerade" similaarly an IP topic would be "Networking-IPX-blah" Whilst the nasmes would be longer the topic areas would be clearer. Of course this whole issue goes away once we agree on an Open Doc Env. categorisation process (ode-discuss@oswg.org), long file names like Networking-IP-Masquerade are not really an issue. regards Kim From kim@new-smtp2.ihug.com.au Thu May 11 23:30:59 2000 Received: (qmail 234 invoked from network); 12 Jan 2000 01:39:03 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 01:39:03 -0000 Received: from new-smtp2.ihug.com.au (root@new-smtp2.ihug.com.au [203.109.250.28]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id UAA18511 for ; Tue, 11 Jan 2000 20:38:59 -0500 Received: from dfusion.com.au (IDENT:kim@p55-max10.syd.ihug.com.au [206.17.105.183]) by new-smtp2.ihug.com.au (8.9.3/8.9.3) with ESMTP id MAA03644; Wed, 12 Jan 2000 12:38:39 +1100 Sender: kim@new-smtp2.ihug.com.au Message-ID: <387BDACC.2876C952@dfusion.com.au> Date: Wed, 12 Jan 2000 01:37:16 +0000 From: Kim Lester Organization: Datafusion Systems Pty Ltd X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.3.35 i686) X-Accept-Language: en MIME-Version: 1.0 To: Alexander Kirillov CC: gnome-doc-list@gnome.org Subject: Re: gtop docs and various questions References: <20000111143325.A28848@aloss.ukuu.org.uk> <20000111124254.A17610@math.sunysb.edu> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Not really my concern but you might be interested that it is a fact of human perception that all caps words are harder to read than mixed/lower case. All caps words are mentally a lot "louder" than mixed case and can subconsciously put people off. Aren't we humans complex :-) Since GNOME is also a word (which was half the point was it not?) I'd recommend you write it as "Gnome" - a proper noun. It has all the effect of caps whilst being far more visually aesthetic, which is also the point of the project, n'est ce pas? cheers Kim Lester > > > Finally, some gnome-documentation-specific questions. Should > > it be GNOME or Gnome? GNOME is cumbersome and breaks the flow > > to read it. This is very noticeable when I printed it out. > > However, I suspect it's probably the 'proper' way, and most > > of the rest of the docs seem to use that. UNIX, Unix, unix, > > or *nix-like? Are there preferred terms for different concepts? > > Menubar (like programmers write it) or menu-bar (more user- > > friendly?). Toolbar or tool-bar? > > > > Telsa > > > > I'd vote for GNOME, UNIX, menubar and toolbar, thouhg could also live > with Unix. From ke@gnu.franken.de Thu May 11 23:30:59 2000 Received: (qmail 29219 invoked from network); 12 Jan 2000 04:53:07 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 04:53:07 -0000 Received: from rachael.franken.de (rachael.franken.de [193.175.24.38]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id XAA26243 for ; Tue, 11 Jan 2000 23:53:06 -0500 Received: by rachael.franken.de via sendmail with stdio id for gnome-doc-list@gnome.org; Wed, 12 Jan 2000 05:52:40 +0100 (MET) (Smail-3.2 1996-Jul-4 #4 built DST-Sep-8) Received: from chico.franken.de(193.175.24.33) via SMTP by rachael.franken.de, id smtpdAAAa20720; Wed Jan 12 05:51:58 2000 Received: by chico.franken.de with UUCP for kim@dfusion.com.au id m128FlE-005COLC; Wed, 12 Jan 2000 05:51:56 +0100 (MET) Received: by tux.gnu.franken.de (Postfix, from userid 270) id 870EADC245; Wed, 12 Jan 2000 03:48:08 +0100 (CET) Sender: ke@gnu.franken.de To: Kim Lester Cc: gnome-doc-list@gnome.org Subject: Re: gtop docs and various questions References: <20000111143325.A28848@aloss.ukuu.org.uk> <20000111124254.A17610@math.sunysb.edu> <387BDACC.2876C952@dfusion.com.au> From: Karl EICHWALDER Date: 12 Jan 2000 03:48:08 +0100 In-Reply-To: Kim Lester's message of "Wed, 12 Jan 2000 01:37:16 +0000" Message-ID: Lines: 14 User-Agent: Gnus/5.0803 (Gnus v5.8.3) Emacs/20.5 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Kim Lester writes: | Since GNOME is also a word (which was half the point was it not?) | I'd recommend you write it as "Gnome" - a proper noun. Sorry, but we've to write GNOME. Please, have a look at Havoc's reply. Since I know what GNOME stands for, I've no problem to read it; "Gnome" is yust plain wrong ;) -- work: ke@suse.de | : http://www.suse.de/~ke/ | ------ ,__o personal: ke@gnu.franken.de | ------ _-\_<, : http://www.franken.de/users/gnu/ke/ | ------ (*)/'(*) From hobbit@aloss.ukuu.org.uk Thu May 11 23:30:59 2000 Received: (qmail 4371 invoked from network); 12 Jan 2000 07:50:24 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 07:50:24 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id CAA00162 for ; Wed, 12 Jan 2000 02:50:22 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id HAA02088 for gnome-doc-list@gnome.org; Wed, 12 Jan 2000 07:50:24 GMT Date: Wed, 12 Jan 2000 07:50:24 +0000 From: Telsa Gwynne To: gnome-doc-list@gnome.org Subject: Re: gtop docs and various questions Message-ID: <20000112075024.A2077@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <20000111143325.A28848@aloss.ukuu.org.uk> <20000111124254.A17610@math.sunysb.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: On Tue, Jan 11, 2000 at 01:40:41PM -0500 or thereabouts, Havoc Pennington wrote: > Alexander Kirillov writes: > > I'd vote for GNOME, UNIX, menubar and toolbar, thouhg could also live > > with Unix. > > > > UNIX the trademark is officially supposed to be in all-caps; GNOME is > also "officially" (hah) in all caps. Yeah, I had the feeling you'd say that. I still think they are more distracting and "technical-looking" to read like that, but oh well. "UNIX-like" is particularly ugly, somehow. Thanks. Telsa From ldp-discuss@LuftHans.com Thu May 11 23:30:59 2000 Received: (qmail 20040 invoked from network); 12 Jan 2000 12:19:09 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 12:19:09 -0000 Received: from mail.LuftHans.com (h-001-115.phoenix.speedchoice.com [24.221.1.115]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id HAA10552 for ; Wed, 12 Jan 2000 07:19:07 -0500 Received: by mail.LuftHans.com (Postfix, from userid 500) id 8DDD4599C6; Wed, 12 Jan 2000 05:17:19 -0700 (MST) Received: from localhost (localhost [127.0.0.1]) by mail.LuftHans.com (Postfix) with ESMTP id 7AC4F59986; Wed, 12 Jan 2000 05:17:19 -0700 (MST) Date: Wed, 12 Jan 2000 05:17:19 -0700 (MST) From: "der.hans" X-Sender: lufthans@gw-int.LuftHans.com To: ldp-discuss@lists.debian.org Cc: gnome-doc-list@gnome.org Subject: Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure] In-Reply-To: <20000112010216.C2700@guylhem.free.fr> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On Wed, 12 Jan 2000, Guylhem Aznar wrote: > On Tue, Jan 11, 2000 at 06:56:38AM -0800, Gregory Leblanc wrote: > > There are two ways of looking at this, the first is to say let's just > > get rid of the mini-HOWTOs and integrate them with the rest of the > > documents. The other option (it seems to me) is to make the distinction > > Quick poll : who would like this? I would like to do away with the distinctions. I dislike having to check one list, then the other. Many of the minis need to be incorporated into the regular howtos or merged together with like topics anyway. For instance, I plan on making a "removable drive HOWTO" as soon as I get my scsi card working with my laptop. This will include stuff from all the Zip and Jaz (mini-)HOWTO, which I believe haven't been updated in eons. The same info applies for Zip, Jaz, Orb, so it should all be in one place having to do with the overall topic. ciao, der.hans -- # +++++++++++=================================+++++++++++ # # der.hans@LuftHans.com # # http://home.pages.de/~lufthans/ # # I'm not anti-social, I'm pro-individual. - der.hans # # ===========+++++++++++++++++++++++++++++++++=========== # From mok@imsb.au.dk Thu May 11 23:30:59 2000 Received: (qmail 31434 invoked from network); 12 Jan 2000 12:56:47 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 12:56:47 -0000 Received: from origo.imsb.au.dk (root@origo.imsb.au.dk [192.38.35.2]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id HAA12330 for ; Wed, 12 Jan 2000 07:56:46 -0500 Received: from origo.imsb.au.dk (IDENT:mok@origo.imsb.au.dk [192.38.35.2]) by origo.imsb.au.dk (8.9.3/8.9.3) with ESMTP id OAA00560; Wed, 12 Jan 2000 14:04:35 +0100 Date: Wed, 12 Jan 2000 14:04:34 +0100 (CET) From: Morten Kjeldgaard To: "der.hans" cc: ldp-discuss@lists.debian.org, gnome-doc-list@gnome.org, recipient list not shown: ; Subject: Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure] In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On Wed, 12 Jan 2000, der.hans wrote: > Many of the minis need to be incorporated into the regular howtos or > merged together with like topics anyway. For instance, I plan on making a > "removable drive HOWTO" as soon as I get my scsi card working with my It is Great that you want to update these documents but I think it would be _much_ better to keep them separate, and use the document tree structure to group them. Thus, you'd have a "Removable Drive" category containing the documents on JAZ, ZIP, floppy, etc. The reasons for keeping several smaller documents are: 1) A monolithic document is harder to maintain, even if there are several people maintaining it. 2) You don't normally need it. For example, if I need information on a ZIP drive, I don't want to waste paper printing out information on JAZ and floppy drives. 3) Smaller, focused documents are easier to cross-reference, and it is easier to define alternate information paths to them. For example, you may want to group the ZIP drive under "USB devices" as well as "Removable Drives", but it would not be relevant to put JAZ drives in this category. /Morten -- Morten Kjeldgaard | Phone : +45 89 42 50 26 Institute of Molecular and Structural Biology | Fax : +45 86 12 31 78 Aarhus University | Home : +45 86 18 81 80 Gustav Wieds Vej 10 C, DK-8000 Aarhus C, Denmark | icq : 27224900 From kirillov@math.sunysb.edu Thu May 11 23:30:59 2000 Received: (qmail 19878 invoked from network); 12 Jan 2000 14:24:09 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 14:24:09 -0000 Received: from peconic.math.sunysb.edu (mail.math.sunysb.edu [129.49.18.67]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id JAA16716 for ; Wed, 12 Jan 2000 09:24:09 -0500 Received: from copiague.math.sunysb.edu (76-069.dialup.sunysb.edu [129.49.76.69]) by peconic.math.sunysb.edu (8.9.3/8.9.3) with ESMTP id JAA24275 for ; Wed, 12 Jan 2000 09:24:08 -0500 (EST) Received: (from shurik@localhost) by copiague.math.sunysb.edu (8.9.3/8.9.3) id JAA02109; Wed, 12 Jan 2000 09:24:54 -0500 Date: Wed, 12 Jan 2000 09:24:54 -0500 Message-Id: <200001121424.JAA02109@copiague.math.sunysb.edu> X-Authentication-Warning: localhost.localdomain: shurik set sender to kirillov@math.sunysb.edu using -f From: Alexander Kirillov To: gnome-doc-list@gnome.org Subject: cross-referencing Hi, there was a discussion on this list on what is the proper way to reference one GNOME document from another - for example, if I want to refer in the users-guide to documentation for gfontsel. Did the experts (which I am not) agree on something? If not, maybe it is time to resume this discussion... Similarly: we also need mechanism for referring to man pages and info pages - after all, gnome help browser is able to show all of them. Sasha From nils@wombat.dialup.fht-esslingen.de Thu May 11 23:30:59 2000 Received: (qmail 10746 invoked from network); 12 Jan 2000 22:22:56 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 22:22:56 -0000 Received: from rhlx01.fht-esslingen.de (root@rhlx01.fht-esslingen.de [134.108.34.10]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id RAA24631 for ; Wed, 12 Jan 2000 17:22:55 -0500 Received: (from uucp@localhost) by rhlx01.fht-esslingen.de (8.9.3/8.9.3) with UUCP id XAA01950 for gnome-doc-list@gnome.org; Wed, 12 Jan 2000 23:22:54 +0100 Received: from localhost (nils@localhost) by wombat.dialup.fht-esslingen.de (8.9.3/8.9.3) with ESMTP id AAA02481 for ; Wed, 12 Jan 2000 00:43:32 +0100 Date: Wed, 12 Jan 2000 00:43:29 +0100 (CET) From: Nils Philippsen To: gnome-doc-list@gnome.org Subject: Re: gtop docs and various questions In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=ISO-8859-1 Content-Transfer-Encoding: 8BIT On 11 Jan 2000, Havoc Pennington wrote: > Alexander Kirillov writes: > > I'd vote for GNOME, UNIX, menubar and toolbar, thouhg could also live > > with Unix. > > > > UNIX the trademark is officially supposed to be in all-caps; GNOME is > also "officially" (hah) in all caps. You can differentiate here: Digital UNIX is in caps because it's Open Group UNIX, Unix-like operating systems like Linux have only capital 'U'. GNOME is all caps because it's an acronym. Nils -- Nils Philippsen / Berliner Stra�e 39 / D-71229 Leonberg // +49.7152.209647 nils@wombat.dialup.fht-esslingen.de / nils@fht-esslingen.de / nils@redhat.de The use of COBOL cripples the mind; its teaching should, therefore, be regarded as a criminal offence. -- Edsger W. Dijkstra From hp@icon.labs.redhat.com Thu May 11 23:30:59 2000 Received: (qmail 15039 invoked from network); 12 Jan 2000 22:33:09 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 22:33:09 -0000 Received: from icon.labs.redhat.com (root@icon.labs.redhat.com [207.175.42.144]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id RAA25411 for ; Wed, 12 Jan 2000 17:33:08 -0500 Received: (from hp@localhost) by icon.labs.redhat.com (8.9.3/8.9.3) id RAA11681; Wed, 12 Jan 2000 17:29:52 -0500 X-Authentication-Warning: icon.labs.redhat.com: hp set sender to hp@redhat.com using -f Sender: hp@icon.labs.redhat.com To: Nils Philippsen Cc: gnome-doc-list@gnome.org Subject: Re: gtop docs and various questions References: From: Havoc Pennington Date: 12 Jan 2000 17:29:52 -0500 In-Reply-To: Nils Philippsen's message of "Wed, 12 Jan 2000 00:43:29 +0100 (CET)" Message-ID: Lines: 11 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Nils Philippsen writes: > You can differentiate here: Digital UNIX is in caps because it's Open > Group UNIX, Unix-like operating systems like Linux have only capital > 'U'. Well, Linux isn't officially Unix or UNIX at all, the only "official" UNIX is UNIX. You aren't allowed to use Unix to describe things without the open group UNIX brand. (Though in practice, only commercial entities observe this rule.) Havoc From nils@wombat.dialup.fht-esslingen.de Thu May 11 23:30:59 2000 Received: (qmail 24961 invoked from network); 12 Jan 2000 22:49:31 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 12 Jan 2000 22:49:31 -0000 Received: from rhlx01.fht-esslingen.de (root@rhlx01.fht-esslingen.de [134.108.34.10]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id RAA26563 for ; Wed, 12 Jan 2000 17:49:30 -0500 Received: (from uucp@localhost) by rhlx01.fht-esslingen.de (8.9.3/8.9.3) with UUCP id XAA03667; Wed, 12 Jan 2000 23:49:28 +0100 Received: from localhost (nils@localhost) by wombat.dialup.fht-esslingen.de (8.9.3/8.9.3) with ESMTP id XAA04221; Wed, 12 Jan 2000 23:51:43 +0100 Date: Wed, 12 Jan 2000 23:51:43 +0100 (CET) From: Nils Philippsen To: Havoc Pennington cc: gnome-doc-list@gnome.org Subject: Re: gtop docs and various questions In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=ISO-8859-1 Content-Transfer-Encoding: 8BIT On 12 Jan 2000, Havoc Pennington wrote: > Nils Philippsen writes: > > You can differentiate here: Digital UNIX is in caps because it's Open > > Group UNIX, Unix-like operating systems like Linux have only capital > > 'U'. > > Well, Linux isn't officially Unix or UNIX at all, the only "official" > UNIX is UNIX. You aren't allowed to use Unix to describe things > without the open group UNIX brand. (Though in practice, only > commercial entities observe this rule.) Well, I pronounce it "Unix-like" but "Digital UNIX". I know that Linux is just official - uhm - Linux. And the trademark is in all caps. There are things more important. Nils -- Nils Philippsen / Berliner Stra�e 39 / D-71229 Leonberg // +49.7152.209647 nils@wombat.dialup.fht-esslingen.de / nils@fht-esslingen.de / nils@redhat.de The use of COBOL cripples the mind; its teaching should, therefore, be regarded as a criminal offence. -- Edsger W. Dijkstra From nakai@internetsolutions.co.jp Thu May 11 23:30:59 2000 Received: (qmail 4097 invoked by uid 504); 13 Jan 2000 07:12:59 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 4090 invoked from network); 13 Jan 2000 07:12:59 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 13 Jan 2000 07:12:59 -0000 Received: from tokyonet-entrance.astec.co.jp (tokyonet-entrance.astec.co.jp [202.239.16.2]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id CAA20199; Thu, 13 Jan 2000 02:12:52 -0500 Received: from mushroom.astec.co.jp (mushroom.astec.co.jp [172.20.10.50]) by tokyonet-entrance.astec.co.jp (8.9.3+3.2W/3.7W1999/12/24) with ESMTP id QAA15092; Thu, 13 Jan 2000 16:12:50 +0900 (JST) Received: from internetsolutions.co.jp (astec-ppp-005 [192.168.200.5]) by mushroom.astec.co.jp (8.9.3+3.2W/3.7W-astec-mushroom1.0) with ESMTP id QAA12991; Thu, 13 Jan 2000 16:12:47 +0900 (JST) Message-ID: <387D7B4D.B131393E@internetsolutions.co.jp> Date: Thu, 13 Jan 2000 16:14:21 +0900 From: Nakai X-Mailer: Mozilla 4.7 [ja] (Win98; I) X-Accept-Language: ja MIME-Version: 1.0 To: webmaster@gnome.org, docs@gnome.org Subject: Add us to http://developer.gnome.org/arch/translate/teams.html Content-Type: text/plain; charset=iso-2022-jp Content-Transfer-Encoding: 7bit Hello, There is Japanese Translation Team and Traslation Team Coodinator. So please add to http://developer.gnome.org/arch/translate/teams.html Translation Team Web Site: Japan GNOME Users Group http://www.gnome.gr.jp/ Translation Team Coordinator: Yukihiro Nakai nakai@gnome.gr.jp -------------- Yukihiro Nakai From madolica@manna.nl Thu May 11 23:30:59 2000 Received: (qmail 19545 invoked by uid 504); 13 Jan 2000 21:59:29 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 17380 invoked from network); 13 Jan 2000 21:56:29 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 13 Jan 2000 21:56:29 -0000 Received: from discus.nl.uu.net (discus.nl.uu.net [193.67.79.178]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id QAA07397 for ; Thu, 13 Jan 2000 16:56:29 -0500 Received: from ldn51-57.Leiden.NL.net ([193.79.255.148]:1075 "HELO host1.thuis.nl") by discus.nl.uu.net with SMTP id ; Thu, 13 Jan 2000 22:56:08 +0100 From: Madolica Angad Gaur Organization: Manna Automatisering To: docs@gnome.org Subject: Translation user guide to papiamento Date: Thu, 13 Jan 2000 22:51:03 +0100 X-Mailer: KMail [version 1.0.28] Content-Type: text/plain; charset=US-ASCII MIME-Version: 1.0 Message-Id: <00011322554701.01304@host1.thuis.nl> Content-Transfer-Encoding: 7BIT Hi, We are going to start a gnome-papiamento translation team very soon. And we would like to translate the user guide too. What is the procedure ? Kind regards, Madolica Linux consultant Manna Software From d-mueth@uchicago.edu Thu May 11 23:30:59 2000 Received: (qmail 12266 invoked by uid 504); 14 Jan 2000 16:22:00 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 32236 invoked from network); 14 Jan 2000 16:12:18 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 14 Jan 2000 16:12:18 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA31413; Fri, 14 Jan 2000 11:12:17 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id KAA02145; Fri, 14 Jan 2000 10:12:15 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Fri, 14 Jan 2000 10:12:15 -0600 (CST) From: Dan Mueth X-Sender: dmueth@enlightenment.uchicago.edu To: docs@gnome.org cc: Nakai , webmaster@gnome.org Subject: Re: Add us to http://developer.gnome.org/arch/translate/teams.html (fwd) Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII (Sorry if anybody gets this twice. My first reply to docs@gnome.org did not propagate through to the mailing list for some reason.) Hi Yukihiro, There are (at least) two sites which keep track of translation web pages. The developer.gnome.org page you refer to lists project home pages and team leader emails. I do not have CVS access to modify this page, so hopefully somebody else listening will make this change there. I added your page to the other GNOME web page - the "Translated Docs" page off of www.gnome.org. Could you look at this page (http://www.gnome.org/translations.shtml) and tell me if there is anything else I should have here? Note that there appears to be a translation of the GNOME FAQ and GNOME User Guide maintained on the site: http://www.sol.dti.ne.jp/%7ehiyori13/gnome/gnomej.html Dan > Hello, > > There is Japanese Translation Team and Traslation Team Coodinator. > So please add to http://developer.gnome.org/arch/translate/teams.html > > Translation Team Web Site: > > Japan GNOME Users Group http://www.gnome.gr.jp/ > > Translation Team Coordinator: > > Yukihiro Nakai nakai@gnome.gr.jp > > -------------- > Yukihiro Nakai > > > -- > FAQ: Frequently-Asked Questions at http://www.gnome.org/gnomefaq > To unsubscribe: mail gnome-doc-list-request@gnome.org with > "unsubscribe" as the Subject. > From kmaraas@online.no Thu May 11 23:30:59 2000 Received: (qmail 27672 invoked by uid 504); 15 Jan 2000 19:12:56 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 27665 invoked from network); 15 Jan 2000 19:12:56 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 15 Jan 2000 19:12:56 -0000 Received: from online.no (pilt-s.online.no [148.122.208.18]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA03127; Sat, 15 Jan 2000 14:12:55 -0500 Received: from online.no (okofam-gw.online.no [193.214.97.65]) by online.no (8.9.3/8.9.1) with ESMTP id UAA24649; Sat, 15 Jan 2000 20:12:41 +0100 (MET) Sender: kmaraas@online.no Message-ID: <387FBA89.9611D1F3@online.no> Date: Fri, 14 Jan 2000 19:08:41 -0500 From: Kjartan Maraas X-Mailer: Mozilla 4.7 [en] (X11; U; Linux 2.3.38 i686) X-Accept-Language: no, en, fr MIME-Version: 1.0 To: Dan Mueth CC: docs@gnome.org, Nakai , webmaster@gnome.org Subject: Re: Add us to http://developer.gnome.org/arch/translate/teams.html(fwd) References: Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Dan Mueth wrote: > > (Sorry if anybody gets this twice. My first reply to docs@gnome.org did > not propagate through to the mailing list for some reason.) > > Hi Yukihiro, > > There are (at least) two sites which keep track of translation web > pages. The developer.gnome.org page you refer to lists project home pages > and team leader emails. I do not have CVS access to modify this page, so > hopefully somebody else listening will make this change there. I added I have added the coordinator now, sorry for the delay. Is there a web page dedicated to translation to Japanese? If so I'll add it to the translation teams web pages list. Cheers Kjartan Maraas From d-mueth@uchicago.edu Thu May 11 23:30:59 2000 Received: (qmail 26728 invoked from network); 16 Jan 2000 21:22:47 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 16 Jan 2000 21:22:47 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id QAA13883 for ; Sun, 16 Jan 2000 16:22:46 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id PAA13459; Sun, 16 Jan 2000 15:22:45 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Sun, 16 Jan 2000 15:22:45 -0600 (CST) From: Dan Mueth X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org cc: Madolica Angad Gaur Subject: Re: Translation user guide to papiamento (fwd) Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII (Sorry if anybody gets this twice. My first reply appears to have not reached gnome-doc-list.) Hi Madolica, Great! You will want to make sure you are identified on the GNOME Translation Project's Team page: http://developer.gnome.org/arch/translate/teams.html by emailing the maintainer. (I think it is Kjartan Maraas ) You should have a look at: http://developer.gnome.org/arch/translate/ You will also want to be listed at: http://www.gnome.org/translations.shtml so that users can find and use your translated documents. When you have any translated docs or a web page, email me or the gnome-doc-list mailing list with the info and I (or somebody) will include it. You may also consider joining the gnome-i8n and gnome-doc-list mailing lists. See: http://www.gnome.org/mailing-lists/index.shtml for info on joining these lists. Feel free to join in the #gnome and #docs IRC channels at irc.mint.net to meet and chat with other GNOME'ers. Dan > Hi, > > We are going to start a gnome-papiamento translation team very soon. > And we would like to translate the user guide too. > > What is the procedure ? > > Kind regards, > > Madolica > > Linux consultant > Manna Software > > > -- > FAQ: Frequently-Asked Questions at http://www.gnome.org/gnomefaq > To unsubscribe: mail gnome-doc-list-request@gnome.org with > "unsubscribe" as the Subject. > From nakai@internetsolutions.co.jp Thu May 11 23:30:59 2000 Received: (qmail 7946 invoked by uid 504); 17 Jan 2000 04:59:39 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 27414 invoked from network); 17 Jan 2000 04:48:37 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 17 Jan 2000 04:48:37 -0000 Received: from tokyonet-entrance.astec.co.jp (tokyonet-entrance.astec.co.jp [202.239.16.2]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id XAA29092; Sun, 16 Jan 2000 23:48:33 -0500 Received: from mushroom.astec.co.jp (mushroom.astec.co.jp [172.20.10.50]) by tokyonet-entrance.astec.co.jp (8.9.3+3.2W/3.7W1999/12/24) with ESMTP id NAA22670; Mon, 17 Jan 2000 13:48:24 +0900 (JST) Received: from internetsolutions.co.jp (tokyonet-entrance.astec.co.jp [172.20.10.6]) by mushroom.astec.co.jp (8.9.3+3.2W/3.7W-astec-mushroom1.0) with ESMTP id NAA10694; Mon, 17 Jan 2000 13:48:20 +0900 (JST) Message-ID: <38829F16.879AEC1B@internetsolutions.co.jp> Date: Mon, 17 Jan 2000 13:48:22 +0900 From: Yukihiro Nakai Organization: InternetSolutions, Inc. X-Mailer: Mozilla 4.7 [ja] (Win98; I) X-Accept-Language: ja MIME-Version: 1.0 To: Kjartan Maraas CC: Dan Mueth , docs@gnome.org, webmaster@gnome.org Subject: Re: Add us to http://developer.gnome.org/arch/translate/teams.html(fwd) References: <387FBA89.9611D1F3@online.no> Content-Type: text/plain; charset=iso-2022-jp Content-Transfer-Encoding: 7bit Kjartan Maraas wrote: > > Dan Mueth wrote: > > > > (Sorry if anybody gets this twice. My first reply to docs@gnome.org did > > not propagate through to the mailing list for some reason.) > > > > Hi Yukihiro, > > > > There are (at least) two sites which keep track of translation web > > pages. The developer.gnome.org page you refer to lists project home pages > > and team leader emails. I do not have CVS access to modify this page, so > > hopefully somebody else listening will make this change there. I added > > I have added the coordinator now, sorry for the delay. Is there a web > page dedicated to translation to Japanese? If so I'll add it to the > translation teams web pages list. Thanks. We don't have translation contents on our web pages, but we have translation mailing list. So please think Japan GNOME Users Group (http://www.gnome.gr.jp/) for translation team. -------------- Yukihiro Nakai From atle@dozer.skynet.be Thu May 11 23:30:59 2000 Received: (qmail 10783 invoked by uid 504); 18 Jan 2000 12:08:56 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 10780 invoked from network); 18 Jan 2000 12:08:56 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 18 Jan 2000 12:08:56 -0000 Received: from dozer.skynet.be (dozer.skynet.be [195.238.2.36]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id HAA19490 for ; Tue, 18 Jan 2000 07:08:55 -0500 Received: from skynet.be (dialup312.charleroi.skynet.be [194.78.236.184]) by dozer.skynet.be (8.9.3/odie-relay-v1.0) with ESMTP id NAA11167 for ; Tue, 18 Jan 2000 13:08:53 +0100 (MET) Sender: atle@dozer.skynet.be Message-ID: <38832BF8.F0636290@skynet.be> Date: Mon, 17 Jan 2000 14:49:29 +0000 From: Atle X-Mailer: Mozilla 4.51C-Caldera [en] (X11; I; Linux 2.2.5-15 i686) X-Accept-Language: en MIME-Version: 1.0 To: docs@gnome.org Subject: Tutorial Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Hi, I would REALLY like to do the tutorial. This would be quite close to my speciality, in all modesty, I think I could do a decent job of it. It I get anything in return, I would like a copy of all GNOME documentation currently available, downloading in Belgium, where I live is terribly expensive, 1/3 of an average salary goes to the phone company for Internet connections. Please burn me a CD with everything on it, I'll send money if required! In any case, PLEASE LET ME HELP! Atle From kmaraas@online.no Thu May 11 23:30:59 2000 Received: (qmail 22668 invoked by uid 504); 20 Jan 2000 14:56:19 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 22664 invoked from network); 20 Jan 2000 14:56:18 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 20 Jan 2000 14:56:18 -0000 Received: from online.no (pilt-s.online.no [148.122.208.18]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id JAA14782 for ; Thu, 20 Jan 2000 09:56:17 -0500 Received: from online.no (okofam-gw.online.no [193.214.97.65]) by online.no (8.9.3/8.9.1) with ESMTP id PAA03920; Thu, 20 Jan 2000 15:56:14 +0100 (MET) Sender: kmaraas@online.no Message-ID: <388776A0.80E113A@online.no> Date: Thu, 20 Jan 2000 15:57:04 -0500 From: Kjartan Maraas X-Mailer: Mozilla 4.7 [en] (X11; U; Linux 2.3.38 i686) X-Accept-Language: no, en, fr MIME-Version: 1.0 To: Madolica Angad Gaur CC: docs@gnome.org Subject: Re: Translation user guide to papiamento References: <00011322554701.01304@host1.thuis.nl> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Madolica Angad Gaur wrote: > > Hi, > > We are going to start a gnome-papiamento translation team very soon. > And we would like to translate the user guide too. > > What is the procedure ? > If you still need this, here is the address for the registration authority. ISO 639 -- Code for the representation of names of languages Technical contents of ISO 639:1988 (E/F) "Code for the representation of names of languages". Typed by Keld.Simonsen@dkuug.dk 1990-11-30 Two-letter lower-case symbols are used. The Registration Authority for ISO 639 is Infoterm, Osterreiches Normungsinstitut (ON), Postfach 130, A-1021 Vienna, Austria. aa Afar ab Abkhazian af Afrikaans am Amharic ar Arabic as Assamese ay Aymara az Azerbaijani ba Bashkir be Byelorussian bg Bulgarian bh Bihari bi Bislama bn Bengali; Bangla bo Tibetan br Breton ca Catalan co Corsican cs Czech cy Welsh da danish de german dz Bhutani el Greek en English eo Esperanto es Spanish et Estonian eu Basque fa Persian fi Finnish fj Fiji fo Faroese fr French fy Frisian ga Irish gd Scots Gaelic gl Galician gn Guarani gu Gujarati ha Hausa hi Hindi hr Croatian hu Hungarian hy Armenian ia Interlingua ie Interlingue ik Inupiak in Indonesian is Icelandic it Italian iw Hebrew ja Japanese ji Yiddish jw Javanese ka Georgian kk Kazakh kl Greenlandic km Cambodian kn Kannada ko Korean ks Kashmiri ku Kurdish ky Kirghiz la Latin ln Lingala lo Laothian lt Lithuanian lv Latvian, Lettish mg Malagasy mi Maori mk Macedonian ml Malayalam mn Mongolian mo Moldavian mr Marathi ms Malay mt Maltese my Burmese na Nauru ne Nepali nl Dutch no Norwegian oc Occitan om (Afan) Oromo or Oriya pa Punjabi pl Polish ps Pashto, Pushto pt Portuguese qu Quechua rm Rhaeto-Romance rn Kirundi ro Romanian ru Russian rw Kinyarwanda sa Sanskrit sd Sindhi sg Sangro sh Serbo-Croatian si Singhalese sk Slovak sl Slovenian sm Samoan sn Shona so Somali sq Albanian sr Serbian ss Siswati st Sesotho su Sudanese sv Swedish sw Swahili ta Tamil te Tegulu tg Tajik th Thai ti Tigrinya tk Turkmen tl Tagalog tn Setswana to Tonga tr Turkish ts Tsonga tt Tatar tw Twi uk Ukrainian ur Urdu uz Uzbek vi Vietnamese vo Volapuk wo Wolof xh Xhosa yo Yoruba zh Chinese zu Zulu From kirillov@math.sunysb.edu Thu May 11 23:30:59 2000 Received: (qmail 2801 invoked from network); 20 Jan 2000 18:46:06 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 20 Jan 2000 18:46:06 -0000 Received: from peconic.math.sunysb.edu (mail.math.sunysb.edu [129.49.18.67]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA00345 for ; Thu, 20 Jan 2000 13:46:06 -0500 Received: from copiague.math.sunysb.edu (IDENT:root@copiague [129.49.18.192]) by peconic.math.sunysb.edu (8.9.3/8.9.3) with ESMTP id NAA05787; Thu, 20 Jan 2000 13:45:44 -0500 (EST) Received: (from kirillov@localhost) by copiague.math.sunysb.edu (8.9.3/8.9.3) id NAA27900; Thu, 20 Jan 2000 13:45:44 -0500 Date: Thu, 20 Jan 2000 13:45:44 -0500 Message-Id: <200001201845.NAA27900@copiague.math.sunysb.edu> X-Authentication-Warning: copiague.math.sunysb.edu: kirillov set sender to kirillov@math.sunysb.edu using -f From: Alexander Kirillov To: gnome-doc-list@gnome.org Cc: jirka@5z.com Subject: gnome search tool Hi all: I made the first pass at the docs for gnome search tool - take a look at http://www.math.sunysb.edu/~kirillov/gsearch and send me your comments Sasha From p_eyler@hotmail.com Thu May 11 23:30:59 2000 Received: (qmail 4575 invoked from network); 21 Jan 2000 13:50:29 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 21 Jan 2000 13:50:29 -0000 Received: from hotmail.com (f44.law4.hotmail.com [216.33.149.44]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id IAA25525 for ; Fri, 21 Jan 2000 08:50:29 -0500 Received: (qmail 53945 invoked by uid 0); 21 Jan 2000 13:49:53 -0000 Message-ID: <20000121134953.53944.qmail@hotmail.com> Received: from 192.223.252.72 by www.hotmail.com with HTTP; Fri, 21 Jan 2000 05:49:53 PST X-Originating-IP: [192.223.252.72] From: "pat eyler" To: kirillov@math.sunysb.edu, gnome-doc-list@gnome.org Cc: jirka@5z.com Subject: Re: gnome search tool Date: Fri, 21 Jan 2000 08:49:53 EST Mime-Version: 1.0 Content-Type: text/plain; format=flowed Sasha, I like the tutorial. There are a couple of nits, but nothing major that I see. 1) There are a minor grammatical errors throughout the document. 2) The screenshot you give is difficult to read, it would probably be better to give a screen shot of the search before it has started. 3) It would be nice to include a link to a decent tutorial on regexps (http://www.pun.org/bram/Class/Perl/3/RegExp_Tutorial.html might be a good one -- I'm not sure). 4) My impression is that showing an example of the tool in 'real-world' use make things a lot easier to understand. You might want to build a scenario and show how using the GNOME search tool can help solve the problem. -pate >From: Alexander Kirillov >To: gnome-doc-list@gnome.org >CC: jirka@5z.com >Subject: gnome search tool >Date: Thu, 20 Jan 2000 13:45:44 -0500 > >Hi all: > >I made the first pass at the docs for gnome search tool - take a look >at >http://www.math.sunysb.edu/~kirillov/gsearch > >and send me your comments > >Sasha > > >-- > FAQ: Frequently-Asked Questions at http://www.gnome.org/gnomefaq > To unsubscribe: mail gnome-doc-list-request@gnome.org with > "unsubscribe" as the Subject. > ______________________________________________________ Get Your Private, Free Email at http://www.hotmail.com From p_eyler@hotmail.com Thu May 11 23:30:59 2000 Received: (qmail 17248 invoked from network); 21 Jan 2000 15:36:30 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 21 Jan 2000 15:36:30 -0000 Received: from hotmail.com (f72.law4.hotmail.com [216.33.149.72]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id KAA32153 for ; Fri, 21 Jan 2000 10:36:29 -0500 Received: (qmail 52222 invoked by uid 0); 21 Jan 2000 15:35:58 -0000 Message-ID: <20000121153558.52221.qmail@hotmail.com> Received: from 192.223.252.72 by www.hotmail.com with HTTP; Fri, 21 Jan 2000 07:35:58 PST X-Originating-IP: [192.223.252.72] From: "pat eyler" To: gnome-doc-list@gnome.org Subject: more tutorials Date: Fri, 21 Jan 2000 10:35:58 EST Mime-Version: 1.0 Content-Type: text/plain; format=flowed Since Sasha put his drafts up for public comment, I'll do the same. I'm working on some basic gnumeric tutorials, and would appreciate comments on the structure, content, etc. http://tbr.nailed.org/gnumeric/goal-seek/ http://tbr.nailed.org/gnumeric/if/ are the urls. Also, is there as solid dsl hacker here? I'd really like to be able to output the html to produce something more like: http://www.thecia.net/users/pate/ (note that this look is (a) an early draft,and (b) done by hand with various bits not copied correctly from the real tutorial at tbr) thanks, -pate ______________________________________________________ Get Your Private, Free Email at http://www.hotmail.com From dcm@redhat.com Thu May 11 23:31:00 2000 Received: (qmail 29552 invoked by uid 504); 21 Jan 2000 16:34:23 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 12036 invoked from network); 21 Jan 2000 16:02:57 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 21 Jan 2000 16:02:57 -0000 Received: from chelseafc.labs.redhat.com (chelseafc.labs.redhat.com [207.175.42.116]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA01550 for ; Fri, 21 Jan 2000 11:02:57 -0500 Received: (from dcm@localhost) by chelseafc.labs.redhat.com (8.9.3/8.9.3) id LAA03338; Fri, 21 Jan 2000 11:02:37 -0500 X-Authentication-Warning: chelseafc.labs.redhat.com: dcm set sender to dcm@redhat.com using -f To: "pat eyler" cc: docs@gnome.org Subject: Re: more tutorials References: <20000121153558.52221.qmail@hotmail.com> X-URL: From: "David C. Mason" Date: 21 Jan 2000 11:02:36 -0500 In-Reply-To: "pat eyler"'s message of "Fri, 21 Jan 2000 10:35:58 EST" Message-ID: Lines: 37 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii "pat eyler" writes: > are the urls. Also, is there as solid dsl hacker here? I'd really like to > be able to output the html to produce something more like: > > http://www.thecia.net/users/pate/ > > (note that this look is (a) an early draft,and (b) done by hand with various > bits not copied correctly from the real tutorial at tbr) There are many problems with wanting to do this with your doc. First if it is to be read in the gnome help browser (current or the new one) your doc will not look like everyone else's. Plus, the current color scheme of the gnome web site will be changing very soon and it will stick out badly once that is done. I suggest we all use the same dsssl files to build our docs. I have a replacement for the cygnus-both.dsl (default one for Docbook Tools) on cvs in /gnome-docu/gdp/dsssl - it is not fancy, it looks very similar to the default but there are many reasons why the default is the way it is - it is easy to read - easy to navigate - and not everyone has the same tastes when it comes to colors. Once the new gnome help browser comes along we better all have the same looking docs or we will have a very stupid looking help system. Cheers, Dave -- David Mason Red Hat AD Labs dcm@redhat.com From p_eyler@hotmail.com Thu May 11 23:31:00 2000 Received: (qmail 19382 invoked by uid 504); 21 Jan 2000 18:19:02 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 19379 invoked from network); 21 Jan 2000 18:19:02 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 21 Jan 2000 18:19:02 -0000 Received: from hotmail.com (f41.law4.hotmail.com [216.33.149.41]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id NAA12661 for ; Fri, 21 Jan 2000 13:19:02 -0500 Received: (qmail 96776 invoked by uid 0); 21 Jan 2000 18:18:31 -0000 Message-ID: <20000121181831.96775.qmail@hotmail.com> Received: from 192.223.252.72 by www.hotmail.com with HTTP; Fri, 21 Jan 2000 10:18:31 PST X-Originating-IP: [192.223.252.72] From: "pat eyler" To: dcm@redhat.com, p_eyler@hotmail.com Cc: docs@gnome.org Subject: Re: more tutorials Date: Fri, 21 Jan 2000 13:18:31 EST Mime-Version: 1.0 Content-Type: text/plain; format=flowed Hmm, it seems that I was less than clear. I intend to use the standard dsl for output that goes into the cvs tree, but I would like to create something a little bit nicer (to my eyes) for my own web site. Your point is well taken though, all of the docs going into the main tree have the same look. -pate >From: "David C. Mason" >To: "pat eyler" >CC: docs@gnome.org >Subject: Re: more tutorials >Date: 21 Jan 2000 11:02:36 -0500 > >"pat eyler" writes: > > > > are the urls. Also, is there as solid dsl hacker here? I'd really like >to > > be able to output the html to produce something more like: > > > > http://www.thecia.net/users/pate/ > > > > (note that this look is (a) an early draft,and (b) done by hand with >various > > bits not copied correctly from the real tutorial at tbr) > >There are many problems with wanting to do this with your doc. First >if it is to be read in the gnome help browser (current or the new one) >your doc will not look like everyone else's. Plus, the current color >scheme of the gnome web site will be changing very soon and it will >stick out badly once that is done. > >I suggest we all use the same dsssl files to build our docs. I have a >replacement for the cygnus-both.dsl (default one for Docbook Tools) on >cvs in /gnome-docu/gdp/dsssl - it is not fancy, it looks very similar >to the default but there are many reasons why the default is the way >it is - it is easy to read - easy to navigate - and not everyone has >the same tastes when it comes to colors. > >Once the new gnome help browser comes along we better all have the >same looking docs or we will have a very stupid looking help system. > > >Cheers, > >Dave >-- > > David Mason > Red Hat AD Labs > > dcm@redhat.com > > >-- > FAQ: Frequently-Asked Questions at http://www.gnome.org/gnomefaq > To unsubscribe: mail gnome-doc-list-request@gnome.org with > "unsubscribe" as the Subject. > ______________________________________________________ Get Your Private, Free Email at http://www.hotmail.com From markb@ordern.com Thu May 11 23:31:00 2000 Received: (qmail 1630 invoked by uid 504); 22 Jan 2000 10:41:48 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 1627 invoked from network); 22 Jan 2000 10:41:48 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 22 Jan 2000 10:41:48 -0000 Received: from anchor-post-34.mail.demon.net (anchor-post-34.mail.demon.net [194.217.242.92]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id FAA23348 for ; Sat, 22 Jan 2000 05:41:48 -0500 Received: from ordern.demon.co.uk ([158.152.10.215]) by anchor-post-34.mail.demon.net with smtp (Exim 2.12 #1) id 12BxzH-000791-0Y for docs@gnome.org; Sat, 22 Jan 2000 10:41:47 +0000 Received: from localhost(really [127.0.0.1]) by ordern.demon.co.uk via smtpd with smtp id for ; Sat, 22 Jan 2000 10:41:42 +0000 (GMT) (Smail-3.2 1996-Jul-4 #3 built 1997-Jul-26) To: docs@gnome.org Subject: Gnome DocBook Source Required X-Mailer: Mew version 1.94 on XEmacs 21.1 (Bryce Canyon) Mime-Version: 1.0 Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-Id: <20000122104142I.markb@ordern.com> Date: Sat, 22 Jan 2000 10:41:42 GMT From: Mark Burton X-Dispatcher: imput version 991025(IM133) Lines: 15 Hi, I am developing a DocBook to texinfo convertor for the GNU project and rms has asked me to obtain some GNOME document source to ensure that the translator can handle your documents without problems. If you could let me know how to obtain some samples I would be most grateful. Thanks, Mark From markb@ordern.com Thu May 11 23:31:00 2000 Received: (qmail 1954 invoked by uid 504); 22 Jan 2000 10:45:25 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 1951 invoked from network); 22 Jan 2000 10:45:25 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 22 Jan 2000 10:45:25 -0000 Received: from finch-post-10.mail.demon.net (finch-post-10.mail.demon.net [194.217.242.38]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id FAA23393 for ; Sat, 22 Jan 2000 05:45:24 -0500 Received: from ordern.demon.co.uk ([158.152.10.215]) by finch-post-10.mail.demon.net with smtp (Exim 2.12 #1) id 12By2k-000Ggo-0A for docs@gnome.org; Sat, 22 Jan 2000 10:45:24 +0000 Received: from localhost(really [127.0.0.1]) by ordern.demon.co.uk via smtpd with smtp id for ; Sat, 22 Jan 2000 10:45:04 +0000 (GMT) (Smail-3.2 1996-Jul-4 #3 built 1997-Jul-26) Subject: Gnome DocBook Source Required To: docs@gnome.org X-Mailer: Mew version 1.94 on XEmacs 21.1 (Bryce Canyon) Mime-Version: 1.0 Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-Id: <20000122104504G.markb@ordern.com> Date: Sat, 22 Jan 2000 10:45:04 GMT From: Mark Burton X-Dispatcher: imput version 991025(IM133) Lines: 11 Hi, Please ignore my last email, I have just discovered the stuff I need on your web site. Thanks, Mark From kirillov@math.sunysb.edu Thu May 11 23:31:00 2000 Received: (qmail 31038 invoked from network); 24 Jan 2000 15:58:00 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 24 Jan 2000 15:58:00 -0000 Received: from peconic.math.sunysb.edu (mail.math.sunysb.edu [129.49.18.67]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id KAA26721 for ; Mon, 24 Jan 2000 10:58:00 -0500 Received: from copiague.math.sunysb.edu (IDENT:root@copiague [129.49.18.192]) by peconic.math.sunysb.edu (8.9.3/8.9.3) with ESMTP id KAA03195 for ; Mon, 24 Jan 2000 10:57:56 -0500 (EST) Received: (from kirillov@localhost) by copiague.math.sunysb.edu (8.9.3/8.9.3) id KAA07080; Mon, 24 Jan 2000 10:57:56 -0500 Date: Mon, 24 Jan 2000 10:57:56 -0500 Message-Id: <200001241557.KAA07080@copiague.math.sunysb.edu> X-Authentication-Warning: copiague.math.sunysb.edu: kirillov set sender to kirillov@math.sunysb.edu using -f From: Alexander Kirillov To: gnome-doc-list@gnome.org Subject: documentation guidelines Hi, guys, here are some minor suggestions for "documentation guidelines" - if everyone agrees, we'll add them to GDP -Howto (being written now). ------------------------- 1. Application documentation should say which version of the application it documents, e.g. Introduction</> <para> blah-blah-blah This document describes version 1.0.53 of The GNOME Application </para> </sect1> -------------------------- 2. Documentation should contain names of authors of the application itself and the documentation, along with info for submitting bug reports. For small docs, the suggested way is to put it in a separate <sect1> at the very end of the document, e.g. <sect1 id="authors"> <title>Authors</> <para> GNOME Application was written by GNOME Hacker (<email>hacker@gnome.org</>). Please send all comments, suggestions, and bug reports to the <ulink type="http" url="http://bugs.gnome.org">GNOME bug tracking database</>. Instructions for submitting bug reports can be found on-line at <ulink type="http" url="http://bugs.gnome.org/Reporting.html"> http://bugs.gnome.org/Reporting.html</>. </para> <para> This manual was written by GDP Member (<email>you@your.address</>). Please send all comments and suggestions regarding the manual to the GNOME Documentation Project at <email>docs@gnome.org</>. </para> </sect1> ---------------------- 3. If you use any of the trademarks, you should add to <legalnotice> section appropriate legal junk, e.g. <legalnotice> <para> This document can be freely redistributed according to the terms of the GNU General Public License. </para> <para> Linux is a trademark of Linus Torvalds</para> <para> UNIX is a trademark of X/Open Group</para> <para> Macintosh is a trademark of Apple, Inc.</para> <para> All other trademarks are property of their owners</para> </legalnotice> ----------------- Do you agree with these? or do you think there are better ways? Let me know. Now, two more sensitive issues: A. Why many docs (in particular, users guide) contain sinister reference to "other operating systems"? Is there a taboo on saying "MS-Windows" or "Macintosh"? For me, it sounded childish. B. Should we include in guidelines a suggestion to use term GNU/Linux rather than Linux? Please do not consider it as a flamebait. We all know what RMS has to say on the matter. I am not asking for a discussion on whether he is right (I personally think he is) or whether it is not worth the inconvenience. I am just asking, whether this should be decided as a matter of GDP guidlines or should be left to individual authors. Best, Sasha From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 13671 invoked from network); 24 Jan 2000 16:43:34 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 24 Jan 2000 16:43:34 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA30227 for <gnome-doc-list@gnome.org>; Mon, 24 Jan 2000 11:43:31 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id QAA05571 for gnome-doc-list@gnome.org; Mon, 24 Jan 2000 16:43:08 GMT Date: Mon, 24 Jan 2000 16:43:08 +0000 From: Telsa Gwynne <hobbit@aloss.ukuu.org.uk> To: gnome-doc-list@gnome.org Subject: Re: documentation guidelines Message-ID: <20000124164308.A5514@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <200001241557.KAA07080@copiague.math.sunysb.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <200001241557.KAA07080@copiague.math.sunysb.edu> On Mon, Jan 24, 2000 at 10:57:56AM -0500 or thereabouts, Alexander Kirillov wrote: > Hi, guys, > here are some minor suggestions for "documentation guidelines" - if > everyone agrees, we'll add them to GDP -Howto (being written now). > ------------------------- > 1. Application documentation should say which version of the > application it documents Good plan. > 2. Documentation should contain names of authors of the application > itself and the documentation, along with info for submitting bug > reports. For small docs, the suggested way is to put it in a > separate <sect1> at the very end of the document, e.g. Don't many of the GNOME documents already have a by-line at the start, in all the bookheader/artheader stuff? But I agree: feedback addresses for programmer and documenter (if different) are good. > (<email>you@your.address</>). Please send all comments > and suggestions regarding the manual to the GNOME Documentation > Project at <email>docs@gnome.org</>. ... And that will solve the problem of what happens when people move on, change email addresses, suddenly recall they should be revising, not reading email, etc :) > ---------------------- > 3. If you use any of the trademarks, you should add to <legalnotice> > section appropriate legal junk, e.g. Can someone tell me how this works? I nicked the layout of the gtop docs from the gnome-terminal one, and this section below magically created the legal notice page although I had done nothing to make this happen. I'm still baffled by how this happens. Someone will have to find a nice list of trademarks and copyrights, then. There's some amazing ones out there. If anyone has access to "In Search of Clusters" by Gregory Pfister, they will be enlightened and entertained by his list of trademarks with his annotations mixed in. "Ethernet is a trademark of Xerox Corp. (I never knew that!)" and so on :) > <legalnotice> > <para> > This document can be freely redistributed according to the > terms of the GNU > General Public License. > </para> > <para> Linux is a trademark of Linus Torvalds</para> > <para> UNIX is a trademark of X/Open Group</para> > <para> Macintosh is a trademark of Apple, Inc.</para> > <para> All other trademarks are property of their owners</para> > </legalnotice> So how's this work to generate the extra page? > Now, two more sensitive issues: > > A. Why many docs (in particular, users guide) contain sinister > reference to "other operating systems"? Is there a taboo on saying > "MS-Windows" or "Macintosh"? For me, it sounded childish. I hadn't noticed this until you pointed it out, but I agree. It makes sense sometimes, but there are occasions when people use it unnecessarily. I know nothing about Windows, but I do have a vague idea what the Next interface was like (I use windowmaker :)). Other people know about what Mac interfaces are like. Putting "other OSs" is not always very clear, whereas a specific reference to the other in question can help someone think, "Oh, that thing" or "Never seen that OS, so I don't need to worry what this was called there." > B. Should we include in guidelines a suggestion to use term GNU/Linux > rather than Linux? Interesting question. I take the point about GNU/Linux, but then we get into the issue of, if the point is to highlight the GNU-based origin of many of the apps and utilities, how to refer to systems where it's a commercial UNIX but it has a bunch of GNU tools on it: a situation that may arise if you have got the GNU tools to compile and install GNOME on Solaris or IRIX. As I understand it, if you're following RMS's reasoning, then you should refer to those as GNU/whatever, too, to indicate that the userland stuff is GNU packages? Perhaps this should be left to individual authors of the programs involved, and for general non-program-specific documentation be left to the writer? The GNU aspect isn't going to be left out: it's the G in GNOME, after all :) I don't know whether this is the right place or not: Dave told me after looking at some of my stuff that there are conventions to do with using DocBook which were not something I had picked up from the book (and I still maintain that, by the book, they're wrong, but hey :)). Perhaps putting those, and any more that crop up, into GDP guidelines would be worth it? The two I have run afould of so far are: o "Even if it looks and acts like a button, if it's not "technically" a button (and a definition would be good here, please), then mark it up as a <guilabel> rather than a <guibutton>" o Don't put things like <guimenuitem> and stuff inside <term> because it gets marked up funny by the Gnome-specific stylesheets. (and I still think the fix is to alter the stylesheet: the book says it's allowed :)) Telsa From ke@gnu.franken.de Thu May 11 23:31:00 2000 Received: (qmail 28373 invoked from network); 25 Jan 2000 06:48:31 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 06:48:31 -0000 Received: from rachael.franken.de (rachael.franken.de [193.175.24.38]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id BAA21784 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 01:48:30 -0500 Received: by rachael.franken.de via sendmail with stdio id <m12Czm8-0027WaC@rachael.franken.de> for gnome-doc-list@gnome.org; Tue, 25 Jan 2000 07:48:28 +0100 (MET) (Smail-3.2 1996-Jul-4 #4 built DST-Sep-8) Received: from chico.franken.de(193.175.24.33) via SMTP by rachael.franken.de, id smtpdAAAa09969; Tue Jan 25 07:47:53 2000 Received: by chico.franken.de with UUCP for gnome-doc-list@gnome.org id m12Czla-005CVcC; Tue, 25 Jan 2000 07:47:54 +0100 (MET) Received: by tux.gnu.franken.de (Postfix, from userid 270) id 1282CDC2A8; Tue, 25 Jan 2000 07:45:35 +0100 (CET) Sender: ke@gnu.franken.de To: Alexander Kirillov <kirillov@math.sunysb.edu> Cc: gnome-doc-list@gnome.org Subject: Re: documentation guidelines References: <200001241557.KAA07080@copiague.math.sunysb.edu> From: Karl EICHWALDER <ke@gnu.franken.de> Date: 25 Jan 2000 07:45:34 +0100 In-Reply-To: Alexander Kirillov's message of "Mon, 24 Jan 2000 10:57:56 -0500" Message-ID: <shemb6sl81.fsf@tux.gnu.franken.de> Lines: 70 User-Agent: Gnus/5.0803 (Gnus v5.8.3) Emacs/20.5 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Alexander Kirillov <kirillov@math.sunysb.edu> writes: | 1. Application documentation should say which version of the | application it documents, e.g. | | <sect1 id="intro"> | <title>Introduction</> | <para> | blah-blah-blah | This document describes version 1.0.53 of The GNOME Application | </para> | </sect1> This is useful info. I'd recommend to store this info as an attribute; maybe, in addition to your human readable text. | -------------------------- | 2. Documentation should contain names of authors of the application | itself and the documentation, along with info for submitting bug | reports. For small docs, the suggested way is to put it in a | separate <sect1> at the very end of the document, e.g. Also useful. Please, consider to use entities: <!DOCTYPE book [ <!ENTITY app-authors "GNOME Hacker1 (<email/hacker1@gnome.org/), GNOME Hacker2 (<email/hacker2@gnome.org/), and GNOME Hacker3 (<email/hacker3@gnome.org/)"> ]> ... <title>Authors</> <para> GNOME Application was written by &app-author;. ... | ---------------------- | 3. If you use any of the trademarks, you should add to <legalnotice> | section appropriate legal junk, e.g. Unfortunately needed... Please, think about an external file (entity) to be include by all manuals: <!DOCTYPE book [ <!ENTITY gnome-tm-list SYSTEM "gnome-tm-list.sgml"> ]> ... &gnome-tm-list; ... where gnome-tm-list.sgml contains <legalnotice>...</legalnotice>; if more appropriate, instead of SYSTEM you can use PUBLIC and resolve the entity via a catlog entry. Once you'll start to use private entities, think careful about namespace problems. | A. Why many docs (in particular, users guide) contain sinister | reference to "other operating systems"? Is there a taboo on saying | "MS-Windows" or "Macintosh"? For me, it sounded childish. That's an rhetoric issue -- the game we all play. Maybe, it has something to do with "damnatio memoriae". -- work: ke@suse.de | : http://www.suse.de/~ke/ | ------ ,__o home: ke@gnu.franken.de | ------ _-\_<, : http://www.franken.de/users/gnu/ke/ | ------ (*)/'(*) From d-mueth@uchicago.edu Thu May 11 23:31:00 2000 Received: (qmail 8393 invoked from network); 25 Jan 2000 16:19:48 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 16:19:48 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA17240 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 11:19:48 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id KAA00492 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 10:19:47 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Tue, 25 Jan 2000 10:19:47 -0600 (CST) From: Dan Mueth <d-mueth@uchicago.edu> X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org Subject: Documentation templates and references Message-ID: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Does the GDP have documentation templates for the various types of docs that accompany an application? After reading sasha's suggestions and questions, it seems like having all the GDP authors start with the same template (which gives examples of these various standards decided on by the GDP) would be a very good idea. This would help authors get started and would help maintain uniform documentation for GNOME applications. If these templates already exist, where are they? We could just say that the documentation for application X is good and can be used as a template, but I don't think this would give us the flexibility to provide a short, yet complete template illustrating all the various markup tags and nomenclature (eg: GNOME, not Gnome) GDP authors should use. Perhaps we should have (1) a simple template with just the basic tags which people use most, and then (2) a more complete GDP reference document which lists the proper markups, nomenclature, etc. Dan (muet) From kirillov@math.sunysb.edu Thu May 11 23:31:00 2000 Received: (qmail 3586 invoked from network); 25 Jan 2000 17:17:10 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 17:17:10 -0000 Received: from peconic.math.sunysb.edu (mail.math.sunysb.edu [129.49.18.67]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA21703 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 12:17:10 -0500 Received: from copiague.math.sunysb.edu (IDENT:root@copiague [129.49.18.192]) by peconic.math.sunysb.edu (8.9.3/8.9.3) with ESMTP id MAA15975 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 12:17:09 -0500 (EST) Received: (from kirillov@localhost) by copiague.math.sunysb.edu (8.9.3/8.9.3) id MAA10329 for gnome-doc-list@gnome.org; Tue, 25 Jan 2000 12:17:09 -0500 Date: Tue, 25 Jan 2000 12:17:09 -0500 From: Alexander Kirillov <kirillov@math.sunysb.edu> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000125121709.D10290@math.sunysb.edu> References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu>; from d-mueth@uchicago.edu on Tue, Jan 25, 2000 at 10:19:47AM -0600 As far as I know, no templates exist at the moment. I could write one - after we agree how it should look like, for example, which external entities we are going to use (see Karl's e-mail). Sasha On Tue, Jan 25, 2000 at 10:19:47AM -0600, Dan Mueth wrote: > > Does the GDP have documentation templates for the various types of docs > that accompany an application? After reading sasha's suggestions and > questions, it seems like having all the GDP authors start with the same > template (which gives examples of these various standards decided on by > the GDP) would be a very good idea. This would help authors get started > and would help maintain uniform documentation for GNOME applications. > >.... > Perhaps we should have (1) a simple template with just the basic tags > which people use most, and then (2) a more complete GDP reference document > which lists the proper markups, nomenclature, etc. > > Dan (muet) > > From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 18063 invoked from network); 25 Jan 2000 19:03:30 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 19:03:30 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA29397 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 14:03:27 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id TAA14366 for gnome-doc-list@gnome.org; Tue, 25 Jan 2000 19:03:04 GMT Date: Tue, 25 Jan 2000 19:03:04 +0000 From: Telsa Gwynne <hobbit@aloss.ukuu.org.uk> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000125190304.I12228@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote: > > Does the GDP have documentation templates for the various types of docs > that accompany an application? After reading sasha's suggestions and No. Dave (? -- someone, anyway :)) and I were talking about this on the docs channel the other day. I had been admiring the FreeBSD's folks' templates and thinking that the only way I ever got started with DocBook was to take someone else's (at least I had the sense to start with a GNOME one to get the same format!) and just mangle it. I made myself my own little template for future reference and was contemplating bulking it out and seeing whether it was any use to anyone. > We could just say that the documentation for application X is good and can > be used as a template, but I don't think this would give us the > flexibility to provide a short, yet complete template illustrating all the > various markup tags and nomenclature (eg: GNOME, not Gnome) GDP authors > should use. > > Perhaps we should have (1) a simple template with just the basic tags > which people use most, and then (2) a more complete GDP reference document > which lists the proper markups, nomenclature, etc. Sasha volunteered before me. I nominate him to do it :) (Also, I think he knows more about DocBook. :) Like exciting things like entities and stuff. And I keep finding more tags I could have used, too, and having to go back and add them.) What I thought would be handy is a sample article and a sample book chapter, with the correct GNOME DTD wotsit at the top, and the boilerplate at the start about authors, and then separate sections on "Different sorts of lists and when to use them. All the words and concepts you _could_ mark up _with_ _examples_" and so on. The DocBook book is great for definitions, but I find it poor on examples of "you have this word and concept and there are two tags that might apply. Which is the one to use?" Telsa From gleblanc@mail.redhat.com Thu May 11 23:31:00 2000 Received: (qmail 285 invoked from network); 25 Jan 2000 19:27:31 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 19:27:31 -0000 Received: from email.cu-portland.edu (email.cu-portland.edu [204.202.196.11]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA30815 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 14:27:30 -0500 Received: from cu-portland.edu (10.64.5.2 [10.64.5.2]) by email.cu-portland.edu with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2650.10) id CDTB5DY3; Tue, 25 Jan 2000 11:27:28 -0800 Sender: gleblanc@mail.redhat.com Message-ID: <388DF95D.965CD4FA@cu-portland.edu> Date: Tue, 25 Jan 2000 11:28:29 -0800 From: Gregory Leblanc <gleblanc@cu-portland.edu> X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.14 i686) X-Accept-Language: en MIME-Version: 1.0 To: Telsa Gwynne <hobbit@aloss.ukuu.org.uk>, gnome-doc-list@gnome.org Subject: Re: Documentation templates and references References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000125190304.I12228@aloss.ukuu.org.uk> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Telsa Gwynne wrote: > > On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote: > > > > Does the GDP have documentation templates for the various types of docs > > that accompany an application? After reading sasha's suggestions and > > No. Dave (? -- someone, anyway :)) and I were talking about this on > the docs channel the other day. I had been admiring the FreeBSD's > folks' templates and thinking that the only way I ever got started > with DocBook was to take someone else's (at least I had the sense > to start with a GNOME one to get the same format!) and just mangle > it. I made myself my own little template for future reference and > was contemplating bulking it out and seeing whether it was any use > to anyone. I haven't looked around the FreeBSD site, but I'll do that later. Do they have anything to go along with the templates, or are they just templates? I'm thinking like some documents that outlike the conventions and proper language style things, although these could be the "content" of the templates, I suppose. I for one would like to take a look at what you've got for purely self-serving reasons. > > > We could just say that the documentation for application X is good and can > > be used as a template, but I don't think this would give us the > > flexibility to provide a short, yet complete template illustrating all the > > various markup tags and nomenclature (eg: GNOME, not Gnome) GDP authors > > should use. > > > > Perhaps we should have (1) a simple template with just the basic tags > > which people use most, and then (2) a more complete GDP reference document > > which lists the proper markups, nomenclature, etc. > > Sasha volunteered before me. I nominate him to do it :) (Also, I think > he knows more about DocBook. :) Like exciting things like entities > and stuff. And I keep finding more tags I could have used, too, and > having to go back and add them.) Everybody seems to have this idea for the doc projects, but I haven't seen anybody write one yet. I've tried a couple of times, but I don't seem to have a good enough knowledge of DocBook to do the technical side, and I'm not clear enough on the best documentation conventions to create that part of it. If Sasha will volunteer, so much the better! :) > > What I thought would be handy is a sample article and a sample > book chapter, with the correct GNOME DTD wotsit at the top, and the > boilerplate at the start about authors, and then separate sections > on "Different sorts of lists and when to use them. All the words > and concepts you _could_ mark up _with_ _examples_" and so on. > The DocBook book is great for definitions, but I find it poor on > examples of "you have this word and concept and there are two tags > that might apply. Which is the one to use?" I think that's technically an "identifier", but whatever. Well, if it's not inline markup, use both? I'm not too clear on when I should use certain tags either, but I'm sure that Norm has a pretty good idea. :) If we give plenty of examples, and if all of the GDP docs are "model docs" within reason, then there should be plenty for people to work from. Greg From d-mueth@uchicago.edu Thu May 11 23:31:00 2000 Received: (qmail 21599 invoked from network); 25 Jan 2000 19:59:34 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 25 Jan 2000 19:59:34 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA00993 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 14:59:34 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id NAA02207 for <gnome-doc-list@gnome.org>; Tue, 25 Jan 2000 13:59:33 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Tue, 25 Jan 2000 13:59:33 -0600 (CST) From: Dan Mueth <d-mueth@uchicago.edu> X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references In-Reply-To: <20000125121709.D10290@math.sunysb.edu> Message-ID: <Pine.LNX.4.10.10001251352290.2107-100000@enlightenment.uchicago.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII > As far as I know, no templates exist at the moment. I could write one > - after we agree how it should look like, for example, which external > entities we are going to use (see Karl's e-mail). > > Sasha Thanks for volunteering Sasha. I have added an entry called "GDP Document Template(s) and Reference Document" into the "General Docs" section of the GDP Documentation Status Table: http://www.gnome.org/gdp/doctable/doctable_list.php3?CategoryID=4 I added you (Sasha) as the primary author for this. When this mailing list thread has died out, anybody can make suggestions using the "Comments" facility of the doctable. Dan From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 19415 invoked from network); 26 Jan 2000 14:58:45 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 14:58:45 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id JAA19447 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 09:58:37 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id OAA14557 for gnome-doc-list@gnome.org; Wed, 26 Jan 2000 14:58:09 GMT Date: Wed, 26 Jan 2000 14:58:09 +0000 From: Telsa Gwynne <hobbit@aloss.ukuu.org.uk> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000126145809.A14195@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote: > If these templates already exist, where are they? ... > Perhaps we should have (1) a simple template with just the basic tags > which people use most, and then (2) a more complete GDP reference document > which lists the proper markups, nomenclature, etc. If these templates come to pass, may I make a small suggestion? I realise that people on virtual consoles or people who limit their windows to 25 lines from top to bottom will hate me for this, but hear me out. Please can we suggest that (a) Ending tags with </> is a bad idea unless it's clearly obvious exactly what it refers to at first glance. Really clearly obvious. (b) Lines should try to avoid being more than eighty characters long before a carriage return. (c) Use lots of whitespace. I was trying to compile the tarball of Balsa today. Not CVS or anything, just the "./configure; make; make install" one. It finally barfed for obscure reasons, but an initial problem I hit was that db2html produced over 200 errors and gave up, aborting the make. I had a poke at the balsa.sgml file to see what had happened. For some reason, db2html didn't like this at the top: <!doctype article PUBLIC "-//Davenport//DTD DocBook V3.1//EN" []> Does anyone see any problems that are obvious there? Is it case- sensitive or something? I was confused. In the end, I altered the "Davenport" to "OASIS" and it removed 95% of the errors. In a fit of enthusiasm I decided to remove the rest of the errors. The usual "this tag shouldn't be here, this tag doesn't have a start tag, you can't have a sect2 starting here" stuff was there. And when I looked, parts of it looked like this: <varlistentry><term>Check Mail Automatically Every...</><listitem><para>If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. <note><para>Using "0" as an interval is a <emphasis>really</> bad idea.</></></></></> </> </> One of those </>s was superfluous and removing that, and putting a </sect2>, elsewhere fixed a lot of it. But it took -ages-! I found it extremely hard to work out which </> referred to which tag. I ended up having to fill in almost all the end-tags and reformat it to use about three times the screen space to know where I was -- but I really think it was more legible. Is this something I just have to get used to, or what? It put me right off using </> for anything, because it gave me a headache trying to work backwards through seven endtags on the trot. But that's why I suggest that too many </> tags are bad! They're hard for new folk, at the very least. It's like counting brackets or something. I suppose I should note that it did at least have documentation, mind you :) And if I could get it to compile, I'd likely be glad about having the documentation to read! Telsa From gleblanc@mail2.aracnet.com Thu May 11 23:31:00 2000 Received: (qmail 23349 invoked from network); 26 Jan 2000 15:47:47 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 15:47:47 -0000 Received: from mail2.aracnet.com (root@mail2.aracnet.com [216.99.193.35]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id KAA22594 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 10:47:46 -0500 Received: from cu-portland.edu (216-99-218-48.dsl.aracnet.com [216.99.218.48]) by mail2.aracnet.com (8.9.3/8.9.3) with ESMTP id HAA32586; Wed, 26 Jan 2000 07:47:29 -0800 Sender: gleblanc@mail2.aracnet.com Message-ID: <388F1712.79762342@cu-portland.edu> Date: Wed, 26 Jan 2000 07:47:30 -0800 From: Gregory Leblanc <gleblanc@cu-portland.edu> X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.14 i586) X-Accept-Language: en MIME-Version: 1.0 To: Telsa Gwynne <hobbit@aloss.ukuu.org.uk>, gnome-doc-list@gnome.org Subject: Re: Documentation templates and references References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Telsa Gwynne wrote: > > On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote: > > If these templates already exist, where are they? > ... > > Perhaps we should have (1) a simple template with just the basic tags > > which people use most, and then (2) a more complete GDP reference document > > which lists the proper markups, nomenclature, etc. > > If these templates come to pass, may I make a small suggestion? > I realise that people on virtual consoles or people who limit their > windows to 25 lines from top to bottom will hate me for this, but > hear me out. > > Please can we suggest that > (a) Ending tags with </> is a bad idea unless it's clearly > obvious exactly what it refers to at first glance. Really clearly > obvious. > (b) Lines should try to avoid being more than eighty characters > long before a carriage return. > (c) Use lots of whitespace. Coming from doing a lot of programming on an Apple IIc, I do these by default, and I have to agree that they're generally good practices. I don't ever use tag minimization, it doesn't save much work, and it makes things impossibly hard to read. > > I was trying to compile the tarball of Balsa today. Not CVS or anything, > just the "./configure; make; make install" one. It finally barfed for > obscure reasons, but an initial problem I hit was that db2html > produced over 200 errors and gave up, aborting the make. I had a > poke at the balsa.sgml file to see what had happened. For some > reason, db2html didn't like this at the top: > > <!doctype article PUBLIC "-//Davenport//DTD DocBook V3.1//EN" []> > > Does anyone see any problems that are obvious there? Well, other than it being an invalid identifier, no. I'm pretty sure that Davenport never had anything to do with 3.1, they moved DocBook to Oasis much eariler than that. > Is it case- > sensitive or something? I was confused. In the end, I altered the > "Davenport" to "OASIS" and it removed 95% of the errors. I'm surprised that it did anything at all with that identifier in there. You might take a peek at your catalog files to see what DTDs you have on your system, so that you know immediately from looking at a source SGML file whether or not you can do anything with it. > In a fit > of enthusiasm I decided to remove the rest of the errors. The usual > "this tag shouldn't be here, this tag doesn't have a start tag, you > can't have a sect2 starting here" stuff was there. And when I looked, > parts of it looked like this: > > <varlistentry><term>Check Mail Automatically > Every...</><listitem><para>If selected, Balsa will connect > to your POP3 servers at the given interval and check for mail. > <note><para>Using "0" as > an interval is a <emphasis>really</> bad idea.</></></></></> > </> > </> Putting multiple </> tags together is a REALLY bad practice, how is one supposed to know what they appply to? A general rule for tag minimization (if you use it at all) is use it ONLY for short inline elements, not for things like <section>. > > One of those </>s was superfluous and removing that, and putting > a </sect2>, elsewhere fixed a lot of it. But it took -ages-! I found > it extremely hard to work out which </> referred to which tag. I > ended up having to fill in almost all the end-tags and reformat it > to use about three times the screen space to know where I was -- but > I really think it was more legible. > > Is this something I just have to get used to, or what? It put me > right off using </> for anything, because it gave me a headache > trying to work backwards through seven endtags on the trot. > > But that's why I suggest that too many </> tags are bad! They're > hard for new folk, at the very least. It's like counting brackets > or something. After both of us ranting, we have one small section of the templates/authors guide written! Thanks Telsa! Depending on how busy I get today, I can try to write up two or three paragraphs on tag minimization. I'll take some of the material here, reference this archived message, and some borrow some more material from what Norm has to say about this in his book. > > I suppose I should note that it did at least have documentation, > mind you :) And if I could get it to compile, I'd likely be glad > about having the documentation to read! After compiling it a couple of months ago, I'm waiting on Evolution. Go Gnome-mailer! Documentation is good, but only if you can read it. Perhaps the SGML source just hasn't been updated in a while (although that means that the content probably hasn't been updated either). Greg From joakim@styx.net Thu May 11 23:31:00 2000 Received: (qmail 12699 invoked from network); 26 Jan 2000 16:45:34 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 16:45:34 -0000 Received: from relay1.mail.styx.net (nocto.styx.net [148.245.18.42]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA27125 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 11:45:33 -0500 Received: from login1.styx.net (login1.styx.net [148.245.18.30]) by relay1.mail.styx.net (Postfix) with ESMTP id F10F53100B for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 10:45:31 -0600 (CST) Received: by login1.styx.net (Postfix, from userid 5004) id 82AEF6C035; Wed, 26 Jan 2000 10:45:31 -0600 (CST) Date: Wed, 26 Jan 2000 10:45:31 -0600 From: Joakim Ziegler <joakim@styx.net> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000126104531.E1713@styx.net> References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <20000126145809.A14195@aloss.ukuu.org.uk>; from hobbit@aloss.ukuu.org.uk on Wed, Jan 26, 2000 at 02:58:09PM +0000 On Wed, Jan 26, 2000 at 02:58:09PM +0000, Telsa Gwynne wrote: > Please can we suggest that > (a) Ending tags with </> is a bad idea unless it's clearly > obvious exactly what it refers to at first glance. Really clearly > obvious. Actually, you should try to avoid them altogether. The Davenport Group is going to move DocBook to XML sooner or later, probably sooner, as a beta DTD already exists, and XML doesn't support </>. In fact, if you avoid this and a couple of other SGML-specific constructs, you'll be able to port the SGML documents to XML without any changes (except the header) when that day comes. -- Joakim Ziegler - styx research director - joakim@styx.net FIX sysop - FIXmud admin - FIDEL & Conglomerate developer From sbaker@debian.org Thu May 11 23:31:00 2000 Received: (qmail 11668 invoked by uid 504); 26 Jan 2000 17:56:20 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 11665 invoked from network); 26 Jan 2000 17:56:20 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 17:56:20 -0000 Received: from master.debian.org (qmailr@master.debian.org [209.41.108.5]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id MAA32489 for <docs@gnome.org>; Wed, 26 Jan 2000 12:56:19 -0500 Received: (qmail 31059 invoked by uid 1368); 26 Jan 2000 17:56:05 -0000 Date: Wed, 26 Jan 2000 11:56:05 -0600 From: Steven Baker <sbaker@debian.org> To: docs@gnome.org Subject: remove from list Message-ID: <20000126115605.A30414@debian.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii User-Agent: Mutt/1.0i Hi there, Was wondering if you'd remove me from the list of Documentation people on the GNOME pages. I have no time to answer email right now, and haven't got reliable internet access. Perhaps inthe future, I'll try to help out. Tia, -Steven From ke@suse.de Thu May 11 23:31:00 2000 Received: (qmail 23542 invoked from network); 26 Jan 2000 18:26:16 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 18:26:15 -0000 Received: from Cantor.suse.de (Cantor.suse.de [194.112.123.193]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA02136 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:26:15 -0500 Received: from Hermes.suse.de (Hermes.suse.de [194.112.123.136]) by Cantor.suse.de (Postfix) with ESMTP id 2ACA81E1CC; Wed, 26 Jan 2000 19:25:44 +0100 (MET) Received: from Wotan.suse.de (Wotan.suse.de [10.10.0.1]) by Hermes.suse.de (Postfix) with ESMTP id A5DC410A034; Wed, 26 Jan 2000 19:25:39 +0100 (MET) Received: from Frechet.suse.de (Frechet.suse.de [10.10.0.123]) by Wotan.suse.de (Postfix) with ESMTP id F058E7F87; Wed, 26 Jan 2000 19:25:15 +0100 (MET) Received: (from ke@localhost) by Frechet.suse.de (8.9.3/8.9.3/SuSE Linux 8.9.3-0.1) id TAA17199; Wed, 26 Jan 2000 19:25:34 +0100 X-Authentication-Warning: Frechet.suse.de: ke set sender to ke@suse.de using -f Sender: ke@suse.de To: Joakim Ziegler <joakim@styx.net> Cc: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> <20000126104531.E1713@styx.net> From: Karl Eichwalder <ke@suse.de> Date: 26 Jan 2000 19:25:33 +0100 In-Reply-To: Joakim Ziegler's message of "Wed, 26 Jan 2000 10:45:31 -0600" Message-ID: <shu2k0adwh.fsf@Frechet.suse.de> Lines: 19 User-Agent: Gnus/5.0804 (Gnus v5.8.4) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Joakim Ziegler <joakim@styx.net> writes: | In fact, if you avoid this and a couple of other SGML-specific | constructs, you'll be able to port the SGML documents to XML without | any changes (except the header) when that day comes. . You'll have to change empty element tags nevertheless. . It will be easy to "convert" SGML documents to XML. . There will be no need to convert SGML documents; they will stay valid forever :) If a writer feels comfortable using SGML minimizations, he should be allowed to use these features. -- work : ke@suse.de Karl Eichwalder home : ke@gnu.franken.de From ke@suse.de Thu May 11 23:31:00 2000 Received: (qmail 30439 invoked from network); 26 Jan 2000 18:28:44 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 18:28:44 -0000 Received: from Cantor.suse.de (Cantor.suse.de [194.112.123.193]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA02372 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:28:43 -0500 Received: from Hermes.suse.de (Hermes.suse.de [194.112.123.136]) by Cantor.suse.de (Postfix) with ESMTP id 0B2D91E1D1; Wed, 26 Jan 2000 19:28:13 +0100 (MET) Received: from Wotan.suse.de (Wotan.suse.de [10.10.0.1]) by Hermes.suse.de (Postfix) with ESMTP id 2555F10A02F; Wed, 26 Jan 2000 19:28:12 +0100 (MET) Received: from Frechet.suse.de (Frechet.suse.de [10.10.0.123]) by Wotan.suse.de (Postfix) with ESMTP id AEF4E7F87; Wed, 26 Jan 2000 19:27:48 +0100 (MET) Received: (from ke@localhost) by Frechet.suse.de (8.9.3/8.9.3/SuSE Linux 8.9.3-0.1) id TAA17218; Wed, 26 Jan 2000 19:28:11 +0100 X-Authentication-Warning: Frechet.suse.de: ke set sender to ke@suse.de using -f Sender: ke@suse.de To: Telsa Gwynne <hobbit@aloss.ukuu.org.uk> Cc: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> From: Karl Eichwalder <ke@suse.de> Date: 26 Jan 2000 19:28:11 +0100 In-Reply-To: Telsa Gwynne's message of "Wed, 26 Jan 2000 14:58:09 +0000" Message-ID: <shpuuoads4.fsf@Frechet.suse.de> Lines: 11 User-Agent: Gnus/5.0804 (Gnus v5.8.4) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Telsa Gwynne <hobbit@aloss.ukuu.org.uk> writes: | One of those </>s was superfluous and removing that, and putting | a </sect2>, elsewhere fixed a lot of it. But it took -ages-! You should have tried `sgmlnorm' first ;-) which come with the jade package. -- work : ke@suse.de Karl Eichwalder home : ke@gnu.franken.de From d-mueth@uchicago.edu Thu May 11 23:31:00 2000 Received: (qmail 29908 invoked from network); 26 Jan 2000 18:50:56 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 18:50:56 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA04191 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:50:55 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id MAA08970; Wed, 26 Jan 2000 12:50:54 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Wed, 26 Jan 2000 12:50:54 -0600 (CST) From: Dan Mueth <d-mueth@uchicago.edu> X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org cc: Steven Baker <sbaker@debian.org> Subject: Re: remove from list In-Reply-To: <20000126115605.A30414@debian.org> Message-ID: <Pine.LNX.4.10.10001261246490.8814-100000@enlightenment.uchicago.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII > Hi there, > Was wondering if you'd remove me from the list of Documentation > people on the GNOME pages. I have no time to answer email right now, > and haven't got reliable internet access. Perhaps inthe future, I'll > try to help out. Steven, I removed you from www.gnome.org/gdp. Do you have a draft of the GNOME Installation/Configuration Guide that somebody else should get from you and continue work on? Dan From godoy@conectiva.com.br Thu May 11 23:31:00 2000 Received: (qmail 5892 invoked from network); 26 Jan 2000 18:53:55 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 18:53:55 -0000 Received: from animaniacs.conectiva.com.br (animaniacs.conectiva.com.br [200.250.58.146]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id NAA04381 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:53:49 -0500 Received: from nexus.conectiva (IDENT:postfix@nexus.conectiva [192.168.255.17]) by animaniacs.conectiva.com.br (8.9.3/8.9.3) with ESMTP id QAA08515; Wed, 26 Jan 2000 16:52:55 -0200 Received: by nexus.conectiva (Postfix, from userid 0) id 1F1BC7C6DA; Wed, 26 Jan 2000 16:52:58 -0200 (BRDT) Date: Wed, 26 Jan 2000 16:52:58 -0200 From: Jorge Godoy <godoy@conectiva.com.br> To: Karl Eichwalder <ke@suse.de> Cc: Telsa Gwynne <hobbit@aloss.ukuu.org.uk>, gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000126165258.C5806@conectiva.com.br> References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> <shpuuoads4.fsf@Frechet.suse.de> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit X-Mailer: Mutt 1.0i In-Reply-To: <shpuuoads4.fsf@Frechet.suse.de>; from ke@suse.de on Wed, Jan 26, 2000 at 07:28:11PM +0100 X-Operating-System: Linux nexus.conectiva 2.2.13-10cl On Wed, Jan 26, 2000 at 07:28:11PM +0100, Karl Eichwalder wrote: > Telsa Gwynne <hobbit@aloss.ukuu.org.uk> writes: > > | One of those </>s was superfluous and removing that, and putting > | a </sect2>, elsewhere fixed a lot of it. But it took -ages-! > > You should have tried `sgmlnorm' first ;-) which come with the jade > package. As a suggestion, why don't you use only "<section>" instead of "<sect1>","<sect2>", etc.? <section> can be nested and it performs the same way as it's numbered friends plus adds the possibility of moving text without having to worry with it's nesting level. -- Godoy. <godoy@conectiva.com.br> GPG Fingerprint 851B B620 626D 2AD0 E783 "Ser poeta n�o � minha ambi��o, E932 1330 BE6D A4A3 0625 � minha maneira de estar sozinho" - Fernando Pessoa. Publica��es @ Conectiva S.A. Except where explicitly stated I speak on my own behalf. Exceto onde explicitado as declara��es aqui feitas s�o apenas minhas. From GLeblanc@cu-portland.edu Thu May 11 23:31:00 2000 Received: (qmail 12443 invoked from network); 26 Jan 2000 19:05:54 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 19:05:54 -0000 Received: from email.cu-portland.edu (email.cu-portland.edu [204.202.196.11]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA05240 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 14:05:53 -0500 Received: by email.cu-portland.edu with Internet Mail Service (5.5.2650.10) id <CDTB5FS5>; Wed, 26 Jan 2000 11:05:50 -0800 Message-ID: <A5F46F4ED18FD211ABEE00105AC6CF077F7B5D@email.cu-portland.edu> From: Gregory Leblanc <GLeblanc@cu-portland.edu> To: "Gnome Doc List (E-mail)" <gnome-doc-list@gnome.org> Subject: RE: Documentation templates and references Date: Wed, 26 Jan 2000 11:05:49 -0800 MIME-Version: 1.0 X-Mailer: Internet Mail Service (5.5.2650.10) Content-Type: text/plain; charset="windows-1252" -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 > -----Original Message----- > From: Karl Eichwalder [mailto:ke@suse.de] > Sent: Wednesday, January 26, 2000 10:26 AM > To: Joakim Ziegler > Subject: Re: Documentation templates and references > > > Joakim Ziegler <joakim@styx.net> writes: > > | In fact, if you avoid this and a couple of other SGML-specific > | constructs, you'll be able to port the SGML documents to > XML without > | any changes (except the header) when that day comes. > > . You'll have to change empty element tags nevertheless. > > . It will be easy to "convert" SGML documents to XML. > > . There will be no need to convert SGML documents; they will > stay valid > forever :) > > If a writer feels comfortable using SGML minimizations, he should > be allowed to use these features. Within reason. If we allow stupid ammounts of minimization as in the example that Telsa posted, then writing in SGML is little or no better than writing in plain text because we can't do anything with it. I'd agree that we shouldn't say "You CAN'T use SGML minimizations", but rather we should say, if you're going to use them, these are some guidelines that you really should follow. Greg -----BEGIN PGP SIGNATURE----- Version: PGPfreeware 6.5.1 for non-commercial use <http://www.pgp.com> iQA/AwUBOI9Fd5LW/u8jW+lnEQJGDACglMbTkJ2fjcTOmS6U+SRkD30a360AoKOu LPQC5HblPMk0NQgaapGWyPrI =Hxnl -----END PGP SIGNATURE----- From joakim@styx.net Thu May 11 23:31:00 2000 Received: (qmail 22797 invoked from network); 26 Jan 2000 19:20:35 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 19:20:35 -0000 Received: from relay1.mail.styx.net (nocto.styx.net [148.245.18.42]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA06173 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 14:20:34 -0500 Received: from login1.styx.net (login1.styx.net [148.245.18.30]) by relay1.mail.styx.net (Postfix) with ESMTP id DB6663100B for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 13:20:32 -0600 (CST) Received: by login1.styx.net (Postfix, from userid 5004) id 795026C035; Wed, 26 Jan 2000 13:20:32 -0600 (CST) Date: Wed, 26 Jan 2000 13:20:32 -0600 From: Joakim Ziegler <joakim@styx.net> To: gnome-doc-list@gnome.org Subject: Re: Documentation templates and references Message-ID: <20000126132032.A14171@styx.net> References: <Pine.LNX.4.10.10001251005350.372-100000@enlightenment.uchicago.edu> <20000126145809.A14195@aloss.ukuu.org.uk> <20000126104531.E1713@styx.net> <shu2k0adwh.fsf@Frechet.suse.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <shu2k0adwh.fsf@Frechet.suse.de>; from ke@suse.de on Wed, Jan 26, 2000 at 07:25:33PM +0100 On Wed, Jan 26, 2000 at 07:25:33PM +0100, Karl Eichwalder wrote: > Joakim Ziegler <joakim@styx.net> writes: >| In fact, if you avoid this and a couple of other SGML-specific >| constructs, you'll be able to port the SGML documents to XML without >| any changes (except the header) when that day comes. > . You'll have to change empty element tags nevertheless. Not necessarily. For instance, <foo></foo> is just as valid as <foo/> for an element defined as EMPTY. This is, I suspect, done to improve SGML interoperability. > . It will be easy to "convert" SGML documents to XML. > . There will be no need to convert SGML documents; they will stay valid > forever :) If tools and stylesheets change to become XML-centric, this need might arise. > If a writer feels comfortable using SGML minimizations, he should be > allowed to use these features. I definitely think the use should be minimized, or even abandoned altogether. It does nothing for readability, and the time savings are minimal. But I'll leave that decision up to others. -- Joakim Ziegler - styx research director - joakim@styx.net FIX sysop - FIXmud admin - FIDEL & Conglomerate developer From GLeblanc@cu-portland.edu Thu May 11 23:31:00 2000 Received: (qmail 149 invoked from network); 26 Jan 2000 20:21:25 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 20:21:25 -0000 Received: from email.cu-portland.edu (email.cu-portland.edu [204.202.196.11]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id PAA09871 for <gnome-doc-list@gnome.org>; Wed, 26 Jan 2000 15:21:24 -0500 Received: by email.cu-portland.edu with Internet Mail Service (5.5.2650.10) id <CDTB5FZP>; Wed, 26 Jan 2000 12:21:19 -0800 Message-ID: <A5F46F4ED18FD211ABEE00105AC6CF077F7B5E@email.cu-portland.edu> From: Gregory Leblanc <GLeblanc@cu-portland.edu> To: "Gnome Doc List (E-mail)" <gnome-doc-list@gnome.org> Subject: On the use of tag minimizations in DocBook Date: Wed, 26 Jan 2000 12:21:18 -0800 MIME-Version: 1.0 X-Mailer: Internet Mail Service (5.5.2650.10) Content-Type: text/plain; charset="iso-8859-1" -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Tag minimizations should be avoided if at all possible. The advantages of tag minimization are few, and the benefits of NOT using them far outweigh these comforts. Below are three examples, each using a different ammount of tag minimization, followed by a short explanation of what's good/bad about each. I'm not going to make any whitespace changes here, although I'll use the same example SGML for the whitespace example. This first one is stolen from the Balsa.sgml file in Balsa version 0.6.0. EXAMPLE 1 <sect2 id="cfgtab-mail-servers"> <title>Mail Servers</> <para>This page lets you specify how you get remove POP3 mail, send mail, etc.</> <variablelist> <varlistentry><term>Remote Mailbox Servers</><listitem><para>These are POP3 servers that you recieve email from. The three buttons let you create, modify, and remove records. POP3 mailboxes will not show up in the mailbox list.</></></> <varlistentry><term>Local Mail Directrory</><listitem><para>This is the directory that Balsa will scan looking for mail folders.</></></> <varlistentry><term>Remote SMTP Server</><listitem><para>If your computer is not equipped with sendmail or you do not wish to use it, select this radio button and enter a hostname to contact via SMTP.</></></> <varlistentry><term>Local Mail User Agent</><listitem><para>Balsa will attempt to use sendmail to send mail. Unfortunately, you cannot specify the command to execute right now.</></></> <varlistentry><term>Check Mail Automatically Every...</><listitem><para>If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. <note><para>Using "0" as an interval is a <emphasis>really</> bad idea.</></></></></> </> </> As you can see, with a bit of work, it's possible to understand where the elements start and end, but just from looking at this, it's not so obvious. If I open this file in an editor with decent syntax highlighting capabilities (emacs with psgml, others), it's much easier to read, but I still have to count the number of tags that are open and closed. Definately not the best SGML that I've ever seen, but it seems to work (mostly). EXAMPLE 2 <sect2 id="cfgtab-mail-servers"> <title>Mail Servers</> <para>This page lets you specify how you get remove POP3 mail, send mail, etc.</> <variablelist> <varlistentry><term>Remote Mailbox Servers</><listitem><para>These are POP3 servers that you recieve email from. The three buttons let you create, modify, and remove records. POP3 mailboxes will not show up in the mailbox list.</para></listitem></varlistentry> <varlistentry><term>Local Mail Directrory</><listitem><para>This is the directory that Balsa will scan looking for mail folders.</para></listitem></varlistentry> <varlistentry><term>Remote SMTP Server</><listitem><para>If your computer is not equipped with sendmail or you do not wish to use it, select this radio button and enter a hostname to contact via SMTP.</para></listitem></varlistentry> <varlistentry><term>Local Mail User Agent</><listitem><para>Balsa will attempt to use sendmail to send mail. Unfortunately, you cannot specify the command to execute right now.</para></listitem></varlistentry> <varlistentry><term>Check Mail Automatically Every...</><listitem><para>If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. <note><para>Using "0" as an interval is a <emphasis>really</> bad idea.</para></para></note></listitem></varlistentry> </variablelist> Well, I changed the tags on this one a bit, adding end tags to a lot of elements. I left a few elements without end tags, because they were close enough together to be obvious (only a couple of words in any tag), and all of the other tags were closed. This is a bit easier to read with a syntax highlighting editor, but that's always going to be the case with markup. This one is certainly acceptable, although perhaps not quite ideal. EXAMPLE 3 <sect2 id="cfgtab-mail-servers"> <title>Mail Servers This page lets you specify how you get remove POP3 mail, send mail, etc. Remote Mailbox ServersThese are POP3 servers that you recieve email from. The three buttons let you create, modify, and remove records. POP3 mailboxes will not show up in the mailbox list. Local Mail DirectroryThis is the directory that Balsa will scan looking for mail folders. Remote SMTP ServerIf your computer is not equipped with sendmail or you do not wish to use it, select this radio button and enter a hostname to contact via SMTP. Local Mail User AgentBalsa will attempt to use sendmail to send mail. Unfortunately, you cannot specify the command to execute right now. Check Mail Automatically Every...If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. Using "0" as an interval is a really bad idea. All of the end tags are included in this example. As you can see, the changes between Example 3 and Example 3 are fairly minimal. This is the easiest, and in my opinion, best, form to have DocBook in, with regards to tag minimization. If you're comfortable with using tag minimizations, feel free to use them as in Example 2, but please try to stay away from things like Example 1. I'll send my Whitespace post in another message a little later today. Greg P.S. I'm going to put a license on this, for safe keeping. We'll have to put this together as something nicer for the thing that I'm calling an "authors guide" at some point. First let's get some content, then somebody can put it together. This message is Copyright (c) 2000 by Gregory Leblanc. This message may be reproduced in whole or in part, without fee, subject to the following restrictions: The copyright notice above and this permission notice must be preserved complete on all complete or partial copies Any translation or derived work must be approved by the author in writing before distribution. Small portions may be reproduced as illustrations for reviews or quotes in other works without this permission notice if proper citation is given. Exceptions to these rules may be granted for academic purposes: Write to the author and ask. These restrictions are here to protect us as authors, not to restrict you as learners and educators. -----BEGIN PGP SIGNATURE----- Version: PGPfreeware 6.5.1 for non-commercial use iQA/AwUBOI9XBJLW/u8jW+lnEQIGrwCggll6K6OYCMb4BUIVMxUHT2LhgfcAoI+p OmVS2jQj6Lcn+MZwaoZt2wW9 =L6yz -----END PGP SIGNATURE----- From GLeblanc@cu-portland.edu Thu May 11 23:31:00 2000 Received: (qmail 8029 invoked from network); 26 Jan 2000 21:49:32 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 26 Jan 2000 21:49:32 -0000 Received: from email.cu-portland.edu (email.cu-portland.edu [204.202.196.11]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id QAA16678 for ; Wed, 26 Jan 2000 16:49:31 -0500 Received: by email.cu-portland.edu with Internet Mail Service (5.5.2650.10) id ; Wed, 26 Jan 2000 13:49:25 -0800 Message-ID: From: Gregory Leblanc To: "Gnome Doc List (E-mail)" Subject: How to use Whitespace. Date: Wed, 26 Jan 2000 13:49:16 -0800 MIME-Version: 1.0 X-Mailer: Internet Mail Service (5.5.2650.10) Content-Type: text/plain; charset="iso-8859-1" -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 After finishing my example on tag minimization, I realized that another big part of the reason that the markup wasn't readable was whitespace. The code below looks pretty good in emacs sgml mode, but looks pretty horrible in Outlook (doing work on finding the totally stupid things that MS did so that Miguel can fix them in Evolution). I've slid things over so that they start at the edge of the page, but everything else is the same as Example 3 in my last episode. Almost, everything, I changed the example number, and added a close tag for sect2. EXAMPLE 1 Mail Servers This page lets you specify how you get remove POP3 mail, send mail, etc. Remote Mailbox ServersThese are POP3 servers that you recieve email from. The three buttons let you create, modify, and remove records. POP3 mailboxes will not show up in the mailbox list. Local Mail DirectroryThis is the directory that Balsa will scan looking for mail folders. Remote SMTP ServerIf your computer is not equipped with sendmail or you do not wish to use it, select this radio button and enter a hostname to contact via SMTP. Local Mail User AgentBalsa will attempt to use sendmail to send mail. Unfortunately, you cannot specify the command to execute right now. Check Mail Automatically Every...If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. Using "0" as an interval is a really bad idea. If you take the time to be careful about reading this, it's not bad at all, and quite workable in a highlighting editor. However, this isn't always possible, so below I've made some changes so that its easier to read. EXAMPLE 1 Mail Servers This page lets you specify how you get remove POP3 mail, send mail, etc. Remote Mailbox Servers These are POP3 servers that you recieve email from. The three buttons let you create, modify, and remove records. POP3 mailboxes will not show up in the mailbox list. Local Mail Directrory This is the directory that Balsa will scan looking for mail folders. Remote SMTP Server If your computer is not equipped with sendmail or you do not wish to use it, select this radio button and enter a hostname to contact via SMTP. Local Mail User Agent Balsa will attempt to use sendmail to send mail. Unfortunately, you cannot specify the command to execute right now. Check Mail Automatically Every... If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. Using "0" as an interval is a really bad idea. I couldn't decide which way looked best, so here is a step between the original and where I stopped. There are no lines longer than 80 characters, including whitespace. I have this erie feeling that mail clients and servers are going to mangle this royally. :-/ If it looks like hell, it's not my fault. Anyway, this one is a bit easier to use. Since in these "lists", there is only 1 listitem, it works out ok. For most other circumstances, it probably wouldn't look quite as good. I've got another example below. EXAMPLE 3 Mail Servers This page lets you specify how you get remove POP3 mail, send mail, etc. Remote Mailbox Servers These are POP3 servers that you recieve email from. The three buttons let you create, modify, and remove records. POP3 mailboxes will not show up in the mailbox list. Local Mail Directrory This is the directory that Balsa will scan looking for mail folders. Remote SMTP Server If your computer is not equipped with sendmail or you do not wish to use it, select this radio button and enter a hostname to contact via SMTP. Local Mail User Agent Balsa will attempt to use sendmail to send mail. Unfortunately, you cannot specify the command to execute right now. Check Mail Automatically Every... If selected, Balsa will connect to your POP3 servers at the given interval and check for mail. Using "0" as an interval is a really bad idea. I might actually have been a little over-zealous on my use of whitespace here, but it is pretty clear which elements go where. When I got everything into this last format, I realized that I'd screwed up which end tags I put where and fixed it. Perhaps I wasn't paying close enough attention, or perhaps I just read the tags wrong in going from to , but however it happened, I fixed it easiest here. Anyway, enjoy! Greg This message is Copyright (c) 2000 by Gregory Leblanc. This message may be reproduced in whole or in part, without fee, subject to the following restrictions: The copyright notice above and this permission notice must be preserved complete on all complete or partial copies Any translation or derived work must be approved by the author in writing before distribution. Small portions may be reproduced as illustrations for reviews or quotes in other works without this permission notice if proper citation is given. Exceptions to these rules may be granted for academic purposes: Write to the author and ask. These restrictions are here to protect us as authors, not to restrict you as learners and educators. -----BEGIN PGP SIGNATURE----- Version: PGPfreeware 6.5.1 for non-commercial use iQA/AwUBOI9rrpLW/u8jW+lnEQJUpQCdHdiaJFGRADdcBwhZRnHzkzBqQJAAoNDh 54QK1/IW+C6XDcoWPmyDze6R =50Wl -----END PGP SIGNATURE----- From ke@gnu.franken.de Thu May 11 23:31:00 2000 Received: (qmail 17546 invoked from network); 27 Jan 2000 02:14:45 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 27 Jan 2000 02:14:45 -0000 Received: from rachael.franken.de (rachael.franken.de [193.175.24.38]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id VAA01714 for ; Wed, 26 Jan 2000 21:14:45 -0500 Received: by rachael.franken.de via sendmail with stdio id for gnome-doc-list@gnome.org; Thu, 27 Jan 2000 03:14:44 +0100 (MET) (Smail-3.2 1996-Jul-4 #4 built DST-Sep-8) Received: from chico.franken.de(193.175.24.33) via SMTP by rachael.franken.de, id smtpdAAAa16756; Thu Jan 27 03:14:05 2000 Received: by chico.franken.de with UUCP for gnome-doc-list@gnome.org id m12DeRh-005CTVC; Thu, 27 Jan 2000 03:14:05 +0100 (MET) Received: by tux.gnu.franken.de (Postfix, from userid 270) id 87971DC2A9; Wed, 26 Jan 2000 20:56:02 +0100 (CET) Sender: ke@gnu.franken.de To: "Gnome Doc List (E-mail)" Subject: Re: Documentation templates and references References: From: Karl EICHWALDER Date: 26 Jan 2000 20:56:02 +0100 In-Reply-To: Gregory Leblanc's message of "Wed, 26 Jan 2000 11:05:49 -0800" Message-ID: Lines: 26 User-Agent: Gnus/5.0803 (Gnus v5.8.3) Emacs/20.5 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Gregory Leblanc writes: | Within reason. If we allow stupid ammounts of minimization as in | the example that Telsa posted, then writing in SGML is little or no | better than writing in plain text because we can't do anything with | it. Yes. Please, take me wrong. I don't vote to accept documents that are basically not maintain. The author may use minimizations, but all submitted documents should be nomalized. The reason: People often complain that they have to press too many keys to write SGML documents. They are astonished once I start to talk about SGML features. Personally, I don't refuse all this overhead (long names, star/end tag, quoted attributes, etc.) -- I'm an Emacs user and therefor I have no problems to write normalized SGML code. But I do accept that vi users don't want to abandon their editor. Does one know vi macros for DocBook editing? -- work: ke@suse.de | : http://www.suse.de/~ke/ | ------ ,__o home: ke@gnu.franken.de | ------ _-\_<, : http://www.franken.de/users/gnu/ke/ | ------ (*)/'(*) From d-mueth@uchicago.edu Thu May 11 23:31:00 2000 Received: (qmail 24471 invoked from network); 27 Jan 2000 14:41:16 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 27 Jan 2000 14:41:16 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id JAA28738 for ; Thu, 27 Jan 2000 09:41:15 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id IAA15074 for ; Thu, 27 Jan 2000 08:41:15 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Thu, 27 Jan 2000 08:41:15 -0600 (CST) From: Dan Mueth X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org Subject: Example GNOME app w/ docs? In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII > Perhaps we should have (1) a simple template with just the basic tags > which people use most, and then (2) a more complete GDP reference document > which lists the proper markups, nomenclature, etc. Does anybody know if there is a full, simple example application ("Hello World") that shows the basics of writing a GNOME app and documentation? If not, perhaps this would be a nice way of illustrating the basics of how GNOME apps and documentation should be layed out, how the Help button connects, how context sensitive help works(when this is finished), etc. Do we need something like this that would act as a simple example for both new GNOME developers and documentation authors? Or does this exist somewhere? Dan From pgc@maths.warwick.ac.uk Thu May 11 23:31:00 2000 Received: (qmail 10558 invoked from network); 27 Jan 2000 15:13:27 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 27 Jan 2000 15:13:27 -0000 Received: from ribble.maths.warwick.ac.uk (ribble.maths.warwick.ac.uk [137.205.232.28]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id KAA30649 for ; Thu, 27 Jan 2000 10:13:26 -0500 Received: from clarke.maths.warwick.ac.uk (clarke [137.205.232.91]) by ribble.maths.warwick.ac.uk (8.9.1/8.9.1) with ESMTP id PAA14067 for ; Thu, 27 Jan 2000 15:13:00 GMT Date: Thu, 27 Jan 2000 16:22:22 +0000 From: Paul Cooper To: gnome-doc-list@gnome.org Subject: Gnome Administrators Guide early beta Message-ID: <20000127162222.H6011@maths.warwick.ac.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In response to Havoc's Project of the Week (#2) I'll finally got round to writing that gnome admin guide I volunteered for a while back ;-0 The url is http://www.maths.warwick.ac.uk/~pgc/gnome/gag2/book1.html Now it is very rough and ready and I fully intend fixing it up (especially need gui* tags adding I know and much reworking of the bad explanantions) but I tried to get most of the structure and content in now as I'm moving house on the weekend and won't be able to hack at it until I get my computer setup in the new place. My intention with the GAG is that (at least to start with) is a series of case studies of gnome in action in a multi user environment. No two places I've ever worked have been alike (other than running some form of unix) so I thought it would be good to get as many viewpoints in as possible. Once we get a few case studies we should be able to distil out some common ground. So this is also a call for volunteers. Please send me your case studies. The three main things I'd like to know are; Background: What machines + unices, what type of users. What are you aiming for. Doesn't have to be fancy, could well be, two P100s, for myself and flatmate, with the intention of having a cool desktop ;-) How you did it: How you set up your default environment, gdm/xdm/kdm/cde/.bash_login/etc, the panel, background, menus, desktop icons etc. i.e. how you catered for the machines and people above. Current Problems: Anything not working / not ideal, partial fixes, etc. Of course add to that whatever you see fit. Preferably in docbook sgml, otherwise plain text will do. Paul -- ------------------------------------------------------- Paul Cooper | pgc@maths.warwick.ac.uk Phd Research Student | 01203 523523 ext. 26320 Room 58 | www.maths.warwick.ac.uk/~pgc/ Mathematics Institute | University of Warwick | Coventry, CV5 7AL | ------------------------------------------------------- From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 10897 invoked from network); 27 Jan 2000 15:13:50 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 27 Jan 2000 15:13:50 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id KAA30694 for ; Thu, 27 Jan 2000 10:13:46 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id PAA22340 for gnome-doc-list@gnome.org; Thu, 27 Jan 2000 15:13:16 GMT Date: Thu, 27 Jan 2000 15:13:16 +0000 From: Telsa Gwynne To: gnome-doc-list@gnome.org Subject: Re: Example GNOME app w/ docs? Message-ID: <20000127151316.D21618@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: On Thu, Jan 27, 2000 at 08:41:15AM -0600 or thereabouts, Dan Mueth wrote: > Does anybody know if there is a full, simple example application ("Hello > World") that shows the basics of writing a GNOME app and documentation? > If not, perhaps this would be a nice way of illustrating the basics of how > GNOME apps and documentation should be layed out, how the Help button > connects, how context sensitive help works(when this is finished), etc. > > Do we need something like this that would act as a simple example for both > new GNOME developers and documentation authors? Or does this exist > somewhere? It exists in parts. The parts are all in the tutorials on developer.gnome.org: Example Hello World Program http://developer.gnome.org/doc/tutorials/gnome-libs/gtk.html#AE (for using GTK) Very Basic GNOME Program http://developer.gnome.org/doc/tutorials/gnome-libs/gnome-programming.html#AEN49 Building GNOME Apps http://developer.gnome.org/doc/tutorials/gnome-libs/building-gnome-apps.html Gnome help system and writing stuff for it for your program: http://developer.gnome.org/doc/tutorials/helpsys.html Programming Guides http://developer.gnome.org/doc/guides/ (a couple more guides there) There is nothing about requiring people to include help and documentation in the programming guides, nor about the common format of "File, Settings, Help" layout of many apps' menubars. I suspect they may be mentioned in the UI Hit Squad page. I'm told there is a standard way to get your program to spot when the help button is pressed and bring up the relevant documentation, but I don't know whether or where it is documented. It might be in the gnome-libs tutorial: everything else seems to be! Telsa From hp@icon.labs.redhat.com Thu May 11 23:31:00 2000 Received: (qmail 25218 invoked from network); 27 Jan 2000 19:19:00 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 27 Jan 2000 19:19:00 -0000 Received: from icon.labs.redhat.com (root@icon.labs.redhat.com [207.175.42.144]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA15033 for ; Thu, 27 Jan 2000 14:18:54 -0500 Received: (from hp@localhost) by icon.labs.redhat.com (8.9.3/8.9.3) id OAA18765; Thu, 27 Jan 2000 14:12:25 -0500 X-Authentication-Warning: icon.labs.redhat.com: hp set sender to hp@redhat.com using -f Sender: hp@icon.labs.redhat.com To: Dan Mueth Cc: gnome-doc-list@gnome.org Subject: Re: Example GNOME app w/ docs? References: From: Havoc Pennington Date: 27 Jan 2000 14:12:24 -0500 In-Reply-To: Dan Mueth's message of "Thu, 27 Jan 2000 08:41:15 -0600 (CST)" Message-ID: Lines: 13 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Dan Mueth writes: > > Does anybody know if there is a full, simple example application ("Hello > World") that shows the basics of writing a GNOME app and documentation? > If not, perhaps this would be a nice way of illustrating the basics of how > GNOME apps and documentation should be layed out, how the Help button > connects, how context sensitive help works(when this is finished), etc. > Module "gnome-hello" in CVS. Havoc From mike@sojurn.lns.pa.us Thu May 11 23:31:00 2000 Received: (qmail 16694 invoked from network); 27 Jan 2000 19:34:40 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 27 Jan 2000 19:34:40 -0000 Received: from sojurn.lns.pa.us (root@188-211.pm4-1.chambersburg.desupernet.net [208.170.188.211]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA16534 for ; Thu, 27 Jan 2000 14:34:39 -0500 Received: from sojurn (IDENT:mike@sojurn [127.0.0.1]) by sojurn.lns.pa.us (8.9.3/8.8.7) with ESMTP id OAA02881 for ; Thu, 27 Jan 2000 14:34:30 -0500 Message-Id: <200001271934.OAA02881@sojurn.lns.pa.us> X-Mailer: exmh version 2.0.2 To: "Gnome Doc List" Subject: Re: Documentation templates and references In-Reply-To: Your message of "26 Jan 2000 20:56:02 +0100." Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Date: Thu, 27 Jan 2000 14:34:30 -0500 From: Mike Sangrey Karl EICHWALDER said: > Personally, I don't refuse all this overhead (long names, star/end > tag, quoted attributes, etc.) -- I'm an Emacs user and therefor I have > no problems to write normalized SGML code. But I do accept that vi > users don't want to abandon their editor. Does one know vi macros for > DocBook editing? I've used 'viper-mode' for years. IMO, it is the best of both worlds. All though it is amusing to see the reaction of die-hard purists (either emacs or vi) when they see how I use emacs/vi to do what I do. ;-) Both say, "How can you do THAT?" -- Mike Sangrey mike@sojurn.lns.pa.us Landisburg, Pa. There is no 'do' in faith, everywhere present within it is 'done'. From drake@x8b4e541f.dhcp.okstate.edu Thu May 11 23:31:00 2000 Received: (qmail 29383 invoked from network); 28 Jan 2000 05:49:36 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 05:49:36 -0000 Received: from okstate.edu (email.okstate.edu [139.78.96.96]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id AAA18725 for ; Fri, 28 Jan 2000 00:49:35 -0500 Received: from x8b4e541f.dhcp.okstate.edu by email.okstate.edu id aa63076; 27 Jan 100 23:43 CST Date: Thu, 27 Jan 2000 23:45:23 -0600 (CST) From: Eric Baudais Reply-To: baudais@okstate.edu To: gnome-doc-list@gnome.org Subject: Xchat Documentation Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Does anyone know if the Online Documentation for Xchat is being converted to Docbook? "They give you illusion that has the appearance of truth. I give you truth in the pleasant disguise of illusion." --Glass Menagerie From d-mueth@uchicago.edu Thu May 11 23:31:00 2000 Received: (qmail 9687 invoked from network); 28 Jan 2000 06:13:23 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 06:13:23 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id BAA19405 for ; Fri, 28 Jan 2000 01:13:22 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id AAA20855; Fri, 28 Jan 2000 00:13:22 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Fri, 28 Jan 2000 00:13:22 -0600 (CST) From: Dan Mueth X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org cc: baudais@okstate.edu Subject: Re: Xchat Documentation In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII > Does anyone know if the Online Documentation for Xchat is being converted > to Docbook? Eric, Not that I know of. If you decide to convert these docs or find somebody who did, could you please notify me so I can update the GNOME Documentation Status Table (http://www.gnome.org/gdp/doctable)? (Or, I can give you an account for the Doctable so you can keep the Xchat documentation status info up-to-date yourself.) Dan From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 5982 invoked from network); 28 Jan 2000 12:10:49 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 12:10:49 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id HAA30569 for ; Fri, 28 Jan 2000 07:10:46 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id MAA28080 for gnome-doc-list@gnome.org; Fri, 28 Jan 2000 12:10:13 GMT Date: Fri, 28 Jan 2000 12:10:13 +0000 From: Telsa Gwynne To: gnome-doc-list@gnome.org Subject: Books or articles? Message-ID: <20000128121013.A27837@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: Havoc wrote: > Dan Mueth writes: > > Does anybody know if there is a full, simple example application ("Hello > > World") that shows the basics of writing a GNOME app and documentation? > > Module "gnome-hello" in CVS. > Havoc I was looking at this. And the other day I sent someone some DocBook for his applet which was in article format, not book format; and he said for some reason it wouldn't include itself when he built it. I'm reasonably sure it's valid DocBook: well, as valid as I get. jade accepts it happily and so on. Only thing I could think of was that perhaps it was because it was in article format. Havoc's example for what is quite a little program is in book format, and that's apparently the demo app. So.. Does every piece of documentation that is going to be accessible from within a program have to be in book format rather than article format? I can't find anything saying so, but of the CVS modules I have, practically everything except white papers and a to-do list is in book format. So I wondered. Also: Havoc's example uses the standard Docbook stuff: Should I be using that, or Dave's PNG-supporting: Telsa From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 28252 invoked from network); 28 Jan 2000 13:26:53 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 13:26:53 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id IAA00172 for ; Fri, 28 Jan 2000 08:26:45 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id NAA28404 for gnome-doc-list@gnome.org; Fri, 28 Jan 2000 13:26:09 GMT Date: Fri, 28 Jan 2000 13:26:09 +0000 From: Telsa Gwynne To: gnome-doc-list@gnome.org Subject: More (sigh) questions: applet docs Message-ID: <20000128132609.C27837@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i I just downloaded the whole of gnome-applets from CVS before wasting your time again with this one, but I didn't find the answer there. I wombled over to the doctable to add an applet as "partly documented, kind of, not yet linked into the program but..". And reading the applet guidelines I saw: All applets should have a Manual, accessible by right clicking on the applet. All applets should have an About, accessible by right clicking on the applet. The top level of all applet documents should be . (This allows us to compile all documents into a single work.) I'm stupid. Does this mean I should just write something omitting this: Blah .... .... ...etc, and just start with Applet Name Blah intro blah And turn all my sect1s into sect2s and 2s into 3s and so on, or what? I tried writing something that started with and db2html grumbled and wouldn't validate it, but created something out of it, at least. (I'm baffled on its naming scheme for the resulting html, mind you!) I haven't quite got as far as entities and making documents that go (stolen from the ORA DocBook book): &ch01; &ch02; But is that the intention here? Then how do I decide what to call the chapter? Just the name of the applet? In that case, will the same file do for the help in the applet itself, or does that have to have enough surrounding it for it to parse properly even in the absence of the other chapters? I would guess the latter. How do I test whether what I am writing is valid DocBook if it doesn't have all that gubbins and just starts with sect2? Add stuff in just for the purpose of testing? db2html won't validate it, it just attempts to process it. I'm sorry, I seem to be asking a lot of questions here :( But I'm terribly confused. I found DocBook and the other tools hard enough to understand at first, then finally got a picture in my head of how they fit together. But having got that far, I still need to know more before apparently being able to produce anything usable. I do read stuff and try things, honestly, but I'm beginning to think it's just too complicated for me. I was really looking forward to the documentation workshop at GUADEC to help me sort some of this out, but apparently that workshop is not happening now :( Telsa From Gabriel_Levan/NetValley@netvalley.fr Thu May 11 23:31:00 2000 Received: (qmail 12629 invoked from network); 28 Jan 2000 14:58:48 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 14:58:48 -0000 Received: from illusion.netvalley.fr (ns.netvalley.fr [212.208.36.168]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id JAA06098 for ; Fri, 28 Jan 2000 09:58:48 -0500 Received: by illusion.netvalley.fr(Lotus SMTP MTA v4.6.4 (830.2 3-23-1999)) id C1256874.005116CA ; Fri, 28 Jan 2000 15:45:42 +0100 X-Lotus-FromDomain: NETVALLEY From: "Gabriel Levan" To: gnome-doc-list@gnome.org Message-ID: Date: Fri, 28 Jan 2000 15:45:39 +0100 Subject: unsusbscribe From hp@icon.labs.redhat.com Thu May 11 23:31:00 2000 Received: (qmail 24269 invoked from network); 28 Jan 2000 15:23:53 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 15:23:53 -0000 Received: from icon.labs.redhat.com (root@icon.labs.redhat.com [207.175.42.144]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id KAA07792 for ; Fri, 28 Jan 2000 10:23:53 -0500 Received: (from hp@localhost) by icon.labs.redhat.com (8.9.3/8.9.3) id KAA27466; Fri, 28 Jan 2000 10:17:17 -0500 X-Authentication-Warning: icon.labs.redhat.com: hp set sender to hp@redhat.com using -f Sender: hp@icon.labs.redhat.com To: Telsa Gwynne Cc: gnome-doc-list@gnome.org Subject: Re: Books or articles? References: <20000128121013.A27837@aloss.ukuu.org.uk> From: Havoc Pennington Date: 28 Jan 2000 10:17:16 -0500 In-Reply-To: Telsa Gwynne's message of "Fri, 28 Jan 2000 12:10:13 +0000" Message-ID: Lines: 14 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Telsa Gwynne writes: > Also: Havoc's example uses the standard Docbook stuff: > > > Should I be using that, or Dave's PNG-supporting: > > My example was written before the PNG variant existed. I think you only need to use the PNG variant if you have PNGs in your docs. :-) I don't know about the article/book issue. Havoc From gleblanc@mail2.aracnet.com Thu May 11 23:31:00 2000 Received: (qmail 27300 invoked from network); 28 Jan 2000 15:26:15 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 15:26:15 -0000 Received: from mail2.aracnet.com (root@mail2.aracnet.com [216.99.193.35]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id KAA07987 for ; Fri, 28 Jan 2000 10:26:14 -0500 Received: from cu-portland.edu (216-99-218-48.dsl.aracnet.com [216.99.218.48]) by mail2.aracnet.com (8.9.3/8.9.3) with ESMTP id HAA09359; Fri, 28 Jan 2000 07:25:53 -0800 Sender: gleblanc@mail2.aracnet.com Message-ID: <3891B500.838641F7@cu-portland.edu> Date: Fri, 28 Jan 2000 07:25:52 -0800 From: Gregory Leblanc X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.14 i586) X-Accept-Language: en MIME-Version: 1.0 To: Telsa Gwynne , gnome-doc-list@gnome.org Subject: Re: More (sigh) questions: applet docs References: <20000128132609.C27837@aloss.ukuu.org.uk> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Telsa Gwynne wrote: > > I just downloaded the whole of gnome-applets from CVS before wasting > your time again with this one, but I didn't find the answer there. > > I wombled over to the doctable to add an applet as "partly documented, > kind of, not yet linked into the program but..". And reading the applet > guidelines I saw: > > All applets should have a Manual, accessible by right clicking on the applet. > All applets should have an About, accessible by right clicking on the applet. > The top level of all applet documents should be . (This allows us to > compile all documents into a single work.) > > I'm stupid. Does this mean I should just write something omitting this: > > > > > Blah > .... > > .... > > > ...etc, and just start with > > > Applet Name > Blah intro blah > > > And turn all my sect1s into sect2s and 2s into 3s and so on, or what? Just turn them into

s. This gets you around the whole problem of knowing which tags, since

can be nested pretty much ad-infinitum. Not sure about the rest of it, but I'd sure like to know. Greg From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 28474 invoked from network); 28 Jan 2000 16:03:51 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 16:03:51 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA10556 for ; Fri, 28 Jan 2000 11:03:49 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id QAA02544 for gnome-doc-list@gnome.org; Fri, 28 Jan 2000 16:03:17 GMT Date: Fri, 28 Jan 2000 16:03:16 +0000 From: Telsa Gwynne To: gnome-doc-list@gnome.org Subject: Re: More (sigh) questions: applet docs Message-ID: <20000128160316.A2384@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <20000128132609.C27837@aloss.ukuu.org.uk> <3891B500.838641F7@cu-portland.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <3891B500.838641F7@cu-portland.edu> On Fri, Jan 28, 2000 at 07:25:52AM -0800 or thereabouts, Gregory Leblanc wrote: > > And turn all my sect1s into sect2s and 2s into 3s and so on, or what? > > Just turn them into

s. This gets you around the whole problem > of knowing which tags, since

can be nested pretty much > ad-infinitum. Not sure about the rest of it, but I'd sure like to know. Yeah, that was my current solution :) Glad to know it's someone else's too :) Telsa From dcm@redhat.com Thu May 11 23:31:00 2000 Received: (qmail 5562 invoked by uid 504); 28 Jan 2000 16:58:25 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 5559 invoked from network); 28 Jan 2000 16:58:25 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 16:58:25 -0000 Received: from chelseafc.labs.redhat.com (chelseafc.labs.redhat.com [207.175.42.116]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA14937 for ; Fri, 28 Jan 2000 11:58:24 -0500 Received: (from dcm@localhost) by chelseafc.labs.redhat.com (8.9.3/8.9.3) id LAA01737; Fri, 28 Jan 2000 11:57:59 -0500 X-Authentication-Warning: chelseafc.labs.redhat.com: dcm set sender to dcm@redhat.com using -f To: Telsa Gwynne cc: docs@gnome.org Subject: Re: Books or articles? References: <20000128121013.A27837@aloss.ukuu.org.uk> X-URL: From: "David C. Mason" Date: 28 Jan 2000 11:57:58 -0500 In-Reply-To: Telsa Gwynne's message of "Fri, 28 Jan 2000 12:10:13 +0000" Message-ID: Lines: 71 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Telsa Gwynne writes: > I was looking at this. And the other day I sent someone some > DocBook for his applet which was in article format, not book > format; and he said for some reason it wouldn't include itself > when he built it. I'm reasonably sure it's valid DocBook: well, > as valid as I get. jade accepts it happily and so on. Only > thing I could think of was that perhaps it was because it was > in article format. > This can only be a problem if the declaration in the document is not correct. For example: if you want an article you put:

blah

if you want a book you put: blah Hell, if you want just a you put blah Jade will parse all of these - no problems (if it is installed correctly and the rest of the document is in order. In the way that DocBook *should* be used - you should use a for a collection of more than one - a for an all encompassing document and an

for, you guessed it, an article. Dave -- David Mason Red Hat AD Labs dcm@redhat.com From dcm@redhat.com Thu May 11 23:31:00 2000 Received: (qmail 10458 invoked from network); 28 Jan 2000 17:02:19 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 17:02:19 -0000 Received: from chelseafc.labs.redhat.com (chelseafc.labs.redhat.com [207.175.42.116]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA15314 for ; Fri, 28 Jan 2000 12:02:19 -0500 Received: (from dcm@localhost) by chelseafc.labs.redhat.com (8.9.3/8.9.3) id MAA01746; Fri, 28 Jan 2000 12:01:56 -0500 X-Authentication-Warning: chelseafc.labs.redhat.com: dcm set sender to dcm@redhat.com using -f To: Gregory Leblanc Cc: Telsa Gwynne , gnome-doc-list@gnome.org Subject: Re: More (sigh) questions: applet docs References: <20000128132609.C27837@aloss.ukuu.org.uk> <3891B500.838641F7@cu-portland.edu> X-URL: From: "David C. Mason" Date: 28 Jan 2000 12:01:56 -0500 In-Reply-To: Gregory Leblanc's message of "Fri, 28 Jan 2000 07:25:52 -0800" Message-ID: Lines: 29 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Gregory Leblanc writes: > > And turn all my sect1s into sect2s and 2s into 3s and so on, or what? > > Just turn them into

s. This gets you around the whole problem > of knowing which tags, since

can be nested pretty much > ad-infinitum. Not sure about the rest of it, but I'd sure like to know. > Greg Using the generic

can be a messy proposition when it comes time for us to generate a TOC in something like the help browser. Personally I think we should stay away from using them altogether. Telsa, as to your problem, yes you have to follow the recursive constructs set by the DocBook DTD but remember that you don't have to use things like if you don't want to. However, when dealing with Sects - you must have a sect1 to have a sect2. Dave -- David Mason Red Hat AD Labs dcm@redhat.com From GLeblanc@cu-portland.edu Thu May 11 23:31:00 2000 Received: (qmail 13721 invoked from network); 28 Jan 2000 17:09:42 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 17:09:42 -0000 Received: from email.cu-portland.edu (email.cu-portland.edu [204.202.196.11]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA15842 for ; Fri, 28 Jan 2000 12:09:41 -0500 Received: by email.cu-portland.edu with Internet Mail Service (5.5.2650.10) id ; Fri, 28 Jan 2000 09:09:39 -0800 Message-ID: From: Gregory Leblanc To: "'David C. Mason'" , gnome-doc-list@gnome.org Cc: Telsa Gwynne Subject: RE: More (sigh) questions: applet docs Date: Fri, 28 Jan 2000 09:09:37 -0800 MIME-Version: 1.0 X-Mailer: Internet Mail Service (5.5.2650.10) Content-Type: text/plain; charset="windows-1252" -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 > -----Original Message----- > From: David C. Mason [mailto:dcm@redhat.com] > Sent: Friday, January 28, 2000 9:02 AM > To: Gregory Leblanc > Cc: Telsa Gwynne; gnome-doc-list@gnome.org > Subject: Re: More (sigh) questions: applet docs > > > Gregory Leblanc writes: > > > > > And turn all my sect1s into sect2s and 2s into 3s and so > on, or what? > > > > Just turn them into

s. This gets you around the > whole problem > > of knowing which tags, since

can be nested pretty much > > ad-infinitum. Not sure about the rest of it, but I'd sure > like to know. > > Greg > > > Using the generic

can be a messy proposition when it > comes time for us to generate a TOC in something like the help > browser. Personally I think we should stay away from using them > altogether. I don't follow. What are you doing to generate the TOC that isn't smart enough to understand recursion? Maybe that tool just needs somebody to hack on it. Greg -----BEGIN PGP SIGNATURE----- Version: PGPfreeware 6.5.1 for non-commercial use iQA/AwUBOJHNJ5LW/u8jW+lnEQIOJgCeK1AUd5ABNRh2hK+LHQRqeROb8QYAoMLr 8fGI4CcOgyvOO4LF8MQDk5hb =utrI -----END PGP SIGNATURE----- From dcm@redhat.com Thu May 11 23:31:00 2000 Received: (qmail 20611 invoked from network); 28 Jan 2000 17:18:37 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 17:18:37 -0000 Received: from chelseafc.labs.redhat.com (chelseafc.labs.redhat.com [207.175.42.116]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA16499 for ; Fri, 28 Jan 2000 12:18:37 -0500 Received: (from dcm@localhost) by chelseafc.labs.redhat.com (8.9.3/8.9.3) id MAA02205; Fri, 28 Jan 2000 12:17:58 -0500 X-Authentication-Warning: chelseafc.labs.redhat.com: dcm set sender to dcm@redhat.com using -f To: Gregory Leblanc Cc: gnome-doc-list@gnome.org, Telsa Gwynne Subject: Re: More (sigh) questions: applet docs References: X-URL: From: "David C. Mason" Date: 28 Jan 2000 12:17:58 -0500 In-Reply-To: Gregory Leblanc's message of "Fri, 28 Jan 2000 09:09:37 -0800" Message-ID: Lines: 33 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Gregory Leblanc writes: > > Using the generic

can be a messy proposition when it > > comes time for us to generate a TOC in something like the help > > browser. Personally I think we should stay away from using them > > altogether. > > I don't follow. What are you doing to generate the TOC that isn't > smart enough to understand recursion? Maybe that tool just needs > somebody to hack on it. > Greg The problem is that we want to define the format for our various section types in our dsssls - if we use

s we aren't able to do as good a job at that task. As I just told telsa on irc - we need a doc that is a gnome applets doc where people can just submit s or whatever and it all builds as a book. - that way the author of an applet doesn't need to worry about it - the maintainer does. Thats how it is in the users guide now - but since that will be split up - we could use a gnome applets doc maintainer. Dave -- David Mason Red Hat AD Labs dcm@redhat.com From jobezone@yahoo.com Thu May 11 23:31:00 2000 Received: (qmail 9402 invoked from network); 28 Jan 2000 18:33:49 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 18:33:49 -0000 Received: from web215.mail.yahoo.com (web215.mail.yahoo.com [128.11.68.115]) by mail.redhat.com (8.8.7/8.8.7) with SMTP id NAA22282 for ; Fri, 28 Jan 2000 13:33:48 -0500 Received: (qmail 21367 invoked by uid 60001); 28 Jan 2000 18:13:04 -0000 Message-ID: <20000128181304.21366.qmail@web215.mail.yahoo.com> Received: from [194.65.213.34] by web215.mail.yahoo.com; Fri, 28 Jan 2000 10:13:04 PST Date: Fri, 28 Jan 2000 10:13:04 -0800 (PST) From: Eduardo Silva Subject: Re: Gnome Administrators Guide early beta To: gnome-doc-list@gnome.org MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii But your plan will be to iclude all these different administration experiences? Wouldn't it be better to in the end create one Super administration experience wich covers all the possibilities(or the most)? Eduardo --- Paul Cooper wrote: > > In response to Havoc's Project of the Week (#2) I'll > finally got round > to writing that gnome admin guide I volunteered for > a while back ;-0 > > The url is > http://www.maths.warwick.ac.uk/~pgc/gnome/gag2/book1.html > > Now it is very rough and ready and I fully intend > fixing it up > (especially need gui* tags adding I know and much > reworking of the bad > explanantions) but I tried to get most of the > structure and content in > now as I'm moving house on the weekend and won't be > able to hack at it > until I get my computer setup in the new place. > > My intention with the GAG is that (at least to start > with) is a series > of case studies of gnome in action in a multi user > environment. No two > places I've ever worked have been alike (other than > running some form > of unix) so I thought it would be good to get as > many viewpoints in as > possible. Once we get a few case studies we should > be able to distil > out some common ground. > > So this is also a call for volunteers. Please send > me your case > studies. The three main things I'd like to know > are; > > Background: What machines + unices, what type of > users. What are you > aiming for. Doesn't have to be fancy, could well be, > two P100s, for > myself and flatmate, with the intention of having a > cool desktop ;-) > > How you did it: How you set up your default > environment, > gdm/xdm/kdm/cde/.bash_login/etc, the panel, > background, menus, desktop > icons etc. i.e. how you catered for the machines and > people above. > > Current Problems: Anything not working / not ideal, > partial fixes, > etc. > > Of course add to that whatever you see fit. > Preferably in docbook > sgml, otherwise plain text will do. > > Paul > > > -- > ------------------------------------------------------- > Paul Cooper | pgc@maths.warwick.ac.uk > Phd Research Student | 01203 523523 ext. 26320 > Room 58 | > www.maths.warwick.ac.uk/~pgc/ > > Mathematics Institute | > University of Warwick | > Coventry, CV5 7AL | > ------------------------------------------------------- > > > -- > FAQ: Frequently-Asked Questions at > http://www.gnome.org/gnomefaq > To unsubscribe: mail > gnome-doc-list-request@gnome.org with > "unsubscribe" as the Subject. > > ===== "Article 19 Everyone has the right to freedom of opinion and expression; this right includes freedom to hold opinions without interference and to seek, receive and impart information and ideas through any media and regardless of frontiers." http://www.democracynow.org http://www.webactive.com http://www.indymedia.org __________________________________________________ Do You Yahoo!? Talk to your friends online with Yahoo! Messenger. http://im.yahoo.com From kirillov@math.sunysb.edu Thu May 11 23:31:00 2000 Received: (qmail 7263 invoked from network); 28 Jan 2000 21:10:05 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 28 Jan 2000 21:10:05 -0000 Received: from peconic.math.sunysb.edu (mail.math.sunysb.edu [129.49.18.67]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id QAA01887 for ; Fri, 28 Jan 2000 16:10:04 -0500 Received: from copiague.math.sunysb.edu (IDENT:root@copiague [129.49.18.192]) by peconic.math.sunysb.edu (8.9.3/8.9.3) with ESMTP id QAA15739 for ; Fri, 28 Jan 2000 16:10:03 -0500 (EST) Received: (from kirillov@localhost) by copiague.math.sunysb.edu (8.9.3/8.9.3) id QAA19473 for gnome-doc-list@gnome.org; Fri, 28 Jan 2000 16:10:03 -0500 Date: Fri, 28 Jan 2000 16:10:03 -0500 From: Alexander Kirillov To: gnome-doc-list@gnome.org Subject: Re: Books or articles? Message-ID: <20000128161003.A19446@math.sunysb.edu> References: <20000128121013.A27837@aloss.ukuu.org.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <20000128121013.A27837@aloss.ukuu.org.uk>; from hobbit@aloss.ukuu.org.uk on Fri, Jan 28, 2000 at 12:10:13PM +0000 On Fri, Jan 28, 2000 at 12:10:13PM +0000, Telsa Gwynne wrote: > > Does every piece of documentation that is going to be accessible > from within a program have to be in book format rather than > article format? > > I can't find anything saying so, but of the CVS modules I have, > practically everything except white papers and a to-do list is > in book format. So I wondered. IMHO, there is *absolutely* no need to use "book" unless your document is really long, such as users guide or FAQ. If people used book format for documenting, say, gnome-terminal - apparently, they just didn't think much about it, because their book consists only of one chapter. I think, most of the docs better be reformatted as articles. I am not a developer, but I can hardly imagine any unsurmountable problems with linking to docs produced from "article" source. In the templates I am doing, I am using article style. Sasha From gnome-doc-list@rascal.org Thu May 11 23:31:00 2000 Received: (qmail 17015 invoked from network); 30 Jan 2000 00:01:07 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 30 Jan 2000 00:01:07 -0000 Received: from popmail.dircon.co.uk (popmail.dircon.co.uk [194.112.32.33]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id TAA23758 for ; Sat, 29 Jan 2000 19:01:06 -0500 Received: from blah.dircon.co.uk (blah.dircon.co.uk [194.112.43.123]) by popmail.dircon.co.uk with ESMTP id AAA23348 for ; Sun, 30 Jan 2000 00:01:04 GMT Received: by free.blah.dircon.co.uk via smail from stdin id (Debian Smail3.2.0.102) for ; Sun, 30 Jan 2000 00:11:50 +0000 (GMT) Received: from UNKNOWN(10.10.11.3), claiming to be "rat.blah.dircon.co.uk" via SMTP by free, id smtpda17165; Sun Jan 30 00:11:46 2000 Received: (from steve@localhost) by rat.blah.dircon.co.uk (8.9.3/8.8.7) id AAA15122 for gnome-doc-list@gnome.org; Sun, 30 Jan 2000 00:08:24 GMT Date: Sun, 30 Jan 2000 00:08:24 +0000 From: gnome-doc-list@rascal.org To: gnome-doc-list@gnome.org Subject: Re: More (sigh) questions: applet docs Message-ID: <20000130000824.A14923@rat.blah.dircon.co.uk> References: <20000128132609.C27837@aloss.ukuu.org.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <20000128132609.C27837@aloss.ukuu.org.uk>; from hobbit@aloss.ukuu.org.uk on Fri, Jan 28, 2000 at 01:26:09PM +0000 Reply_To: Steve George I think the first question about using sections has been covered pretty well, it leaves three interesting points. On Fri, Jan 28, 2000 at 01:26:09PM +0000, Telsa Gwynne wrote: > > > > > &ch01; > &ch02; > > > But is that the intention here? Then how do I decide what to call > the chapter? Just the name of the applet? In that case, will the > same file do for the help in the applet itself, or does that have > to have enough surrounding it for it to parse properly even in > the absence of the other chapters? I would guess the latter. > Whomever takes control of the 'applets' doc will have to make a Makefile with some shell script to whack them all together. If you look at the desktop docs this it does something along these lines. More interesting is the possibility of dynamic help files depending on what the user has installed since you would have to find the original sgml files and then convert them. I guess the app could tell the system what the name of the helpfile/location was: you could register the names as part of the install in some /etc file: or you could make a fixed path/namespace for the help file names. Anyway, I'll leave all that to the whomever is doing it though it is an interesting idea! > I do read stuff and try things, honestly, but I'm beginning to > think it's just too complicated for me. Well I don't think anyone's worried and you're already pretty close to having a release: like any development it's that old saw about the last 5% taking 50% of the time :) > > I was really looking forward to the documentation workshop at > GUADEC to help me sort some of this out, but apparently that workshop > is not happening now :( > So was I: it's a pity so few external people were interested but hardly suprising as docs has a bad name as being difficult to do and boring. We seem to have more active documenters than a few months ago but need more, learning more about how it all works sounded darned good to me. Hopefully a few people from the GDP and Translations will be at GUADEC, I hope to be. Perhaps we can have an informal meet to discuss docs and GNOME while the developers hack?? Who else is going to be there? Perhaps we can grab whomever is going to develop the help browser to give us an idea about it's capabilities so we'll be prepared, whose doing it anyway? Steve 'blah' George From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 18940 invoked from network); 30 Jan 2000 12:22:30 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 30 Jan 2000 12:22:30 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id HAA10268 for ; Sun, 30 Jan 2000 07:22:27 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id MAA14953 for gnome-doc-list@gnome.org; Sun, 30 Jan 2000 12:21:49 GMT Date: Sun, 30 Jan 2000 12:21:49 +0000 From: Telsa Gwynne To: gnome-doc-list@gnome.org Subject: Re: More (sigh) questions: applet docs Message-ID: <20000130122149.C14882@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <20000128132609.C27837@aloss.ukuu.org.uk> <20000130000824.A14923@rat.blah.dircon.co.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <20000130000824.A14923@rat.blah.dircon.co.uk> > > GUADEC to help me sort some of this out, but apparently that workshop > > is not happening now :( > > So was I: it's a pity so few external people were interested but hardly > suprising as docs has a bad name as being difficult to do and boring. We > seem to have more active documenters than a few months ago but need more, > learning more about how it all works sounded darned good to me. Everyone seems to think they're boring, but I really enjoy them. Then again, I _read_ all the docs, too, which I gather makes me a weirdo:) Difficult: yes. The learning curve is steep. On the other hand, when you're on it is the best time to help other people, sometimes, because the same problems they have are the ones you just figured out or had explained to you. (And on that note, I should say thank you to everyone who keeps answering my questions here. It really is much appreciated.) > Hopefully a few people from the GDP and Translations will be at GUADEC, > I hope to be. Perhaps we can have an informal meet to discuss docs and > GNOME while the developers hack?? Who else is going to be there? Yes! I'm definitely up for that. Who else? Telsa From mathieu@mathieu.rezel.enst.fr Thu May 11 23:31:00 2000 Received: (qmail 20547 invoked from network); 30 Jan 2000 16:25:48 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 30 Jan 2000 16:25:48 -0000 Received: from enst.enst.fr (enst.enst.fr [137.194.2.16]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA17228 for ; Sun, 30 Jan 2000 11:25:44 -0500 Received: from email.enst.fr (muse.enst.fr [137.194.2.33]) by enst.enst.fr (8.9.1a/8.9.1) with ESMTP id RAA04736 for ; Sun, 30 Jan 2000 17:25:38 +0100 (MET) Received: from mathieu.rezel.enst.fr (mathieu.rezel.enst.fr [137.194.8.56]) by email.enst.fr (8.9.3/8.9.3) with ESMTP id RAA18318 for ; Sun, 30 Jan 2000 17:25:38 +0100 (MET) Received: from mathieu by mathieu.rezel.enst.fr with local (Exim 3.12 #1 (Debian)) id 12F2z0-0004om-00; Sun, 30 Jan 2000 23:38:14 +0100 To: gnome-doc-list@gnome.org Subject: folowup Mime-Version: 1.0 (generated by tm-edit 7.106) Content-Type: text/plain; charset=US-ASCII From: lacage@email.enst.fr (Mathieu Lacage) Date: 30 Jan 2000 23:38:14 +0100 Message-ID: <87oga36v8p.fsf@mathieu.rezel.enst.fr> Lines: 30 X-Mailer: Gnus v5.5/XEmacs 20.4 - "Emerald" Sender: Mathieu Lacage Hi, I am one of the organizers of GUADEC. Telsa Gwynne writes: > > > GUADEC to help me sort some of this out, but apparently that workshop > > > is not happening now :( yes, we are sorry for this. > > Hopefully a few people from the GDP and Translations will be at GUADEC, > > I hope to be. Perhaps we can have an informal meet to discuss docs and I can manage to setup some place for those of you who will be there to discuss all this. All you have to do is to send me a mail to mathieu@advogato.org with "GUADEC doc" as subject. -> when I know how much you'll be, I'll manage to setup something. With nice Gnome T-shirts ? ;) > > GNOME while the developers hack?? Who else is going to be there? > > Yes! I'm definitely up for that. Who else? > > Telsa Mathieu From gleblanc@mail4.aracnet.com Thu May 11 23:31:00 2000 Received: (qmail 27346 invoked from network); 30 Jan 2000 19:31:38 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 30 Jan 2000 19:31:38 -0000 Received: from mail4.aracnet.com (root@mail4.aracnet.com [216.99.193.36]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id OAA23797 for ; Sun, 30 Jan 2000 14:31:37 -0500 Received: from cu-portland.edu (216-99-218-48.dsl.aracnet.com [216.99.218.48]) by mail4.aracnet.com (8.9.3/8.9.3) with ESMTP id LAA08355 for ; Sun, 30 Jan 2000 11:31:45 -0800 Sender: gleblanc@mail4.aracnet.com Message-ID: <38949196.D37D59CA@cu-portland.edu> Date: Sun, 30 Jan 2000 11:31:34 -0800 From: Gregory Leblanc X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.14 i586) X-Accept-Language: en MIME-Version: 1.0 To: gnome-doc-list@gnome.org Subject: Re: More (sigh) questions: applet docs References: <20000128132609.C27837@aloss.ukuu.org.uk> <20000130000824.A14923@rat.blah.dircon.co.uk> <20000130122149.C14882@aloss.ukuu.org.uk> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Telsa Gwynne wrote: > > > > GUADEC to help me sort some of this out, but apparently that workshop > > > is not happening now :( > > > > So was I: it's a pity so few external people were interested but hardly > > suprising as docs has a bad name as being difficult to do and boring. We > > seem to have more active documenters than a few months ago but need more, > > learning more about how it all works sounded darned good to me. > > Everyone seems to think they're boring, but I really enjoy them. > Then again, I _read_ all the docs, too, which I gather makes me a > weirdo :) Difficult: yes. The learning curve is steep. On the other > hand, when you're on it is the best time to help other people, > sometimes, because the same problems they have are the ones you > just figured out or had explained to you. (And on that note, I > should say thank you to everyone who keeps answering my questions > here. It really is much appreciated.) I tend to do the same things. It's just that some people are cut out for hacking, and others are cut out for the 'real work' of writing the documentation for it. I'll have to check out the documents in the gnome-hello module, and see if we can get enough good things there for gnome-hello-doc? module. > > > Hopefully a few people from the GDP and Translations will be at GUADEC, > > I hope to be. Perhaps we can have an informal meet to discuss docs and > > GNOME while the developers hack?? Who else is going to be there? > > Yes! I'm definitely up for that. Who else? Drat, too far for us in the US... Greg From d-mueth@uchicago.edu Thu May 11 23:31:00 2000 Received: (qmail 10648 invoked from network); 31 Jan 2000 03:16:17 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 03:16:17 -0000 Received: from enlightenment.uchicago.edu (root@enlightenment.uchicago.edu [128.135.132.158]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id WAA11771 for ; Sun, 30 Jan 2000 22:16:17 -0500 Received: from localhost (dmueth@localhost) by enlightenment.uchicago.edu (8.9.3/8.9.3) with ESMTP id VAA06909 for ; Sun, 30 Jan 2000 21:16:13 -0600 X-Authentication-Warning: enlightenment.uchicago.edu: dmueth owned process doing -bs Date: Sun, 30 Jan 2000 21:16:13 -0600 (CST) From: Dan Mueth X-Sender: dmueth@enlightenment.uchicago.edu To: gnome-doc-list@gnome.org Subject: The GNOME Handbook of Writing Software Documentation Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII This weekend I started the GNOME Handbook of Writing Software Documentation in CVS at gnome-docu/gdp/gdp-handbook.sgml. I also put it on the web at http://www.gnome.org/gdp/gdp-handbook/. While I have written rough drafts of some sections, other are just a few comments of what I thought should go in them. I am not really qualified to write several sections of the Handbook, and other parts may have to be decided upon after discussion on this list. I would like to encourage GDP members to look at this document and suggest additions/improvements or make commits directly. Note that one section, "GDP Documentation Conventions" is meant to hold all the numerous conventions the GDP decides upon, such as use of section tags, formatting, use of SGML minimizations, etc. Presumably we can fill this section in just by going through the mailing list archives. Comments on other sections: Appendix A: Examples - I intend this to be filled with examples of each type of document. Appendix B: Templates - These are templates for each common type of document. I believe Sasha plans on writing these. Appendix C: Commonly Used Tags - Everybody feel free to add things here. The GNOME Documentation System - dcm - I think you are the only person qualified to describe this. I think a lot of us will enjoy reading this when you are done. I, for one, am still pretty confused about how this works. Installing and Using DocBook - I think blah plans on writing the remaining portions of this. Basics of Documentation Style - Any good writers among us who can tell us all how to be good writers? Telsa will be adding a section explaining how to write good DocBook. Note I merged parts of the HOWTO into the Handbook, but not all of it yet. All feedback is welcome:) Dan From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 26346 invoked from network); 31 Jan 2000 09:00:26 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 09:00:26 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id EAA23446 for ; Mon, 31 Jan 2000 04:00:24 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id IAA18965 for gnome-doc-list@gnome.org; Mon, 31 Jan 2000 08:59:43 GMT Date: Mon, 31 Jan 2000 08:59:43 +0000 From: Telsa Gwynne To: gnome-doc-list@gnome.org Subject: Re: folowup Message-ID: <20000131085943.B17462@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: <87oga36v8p.fsf@mathieu.rezel.enst.fr> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <87oga36v8p.fsf@mathieu.rezel.enst.fr> Steve wrote: > > > Hopefully a few people from the GDP and Translations will be at GUADEC, > > > I hope to be. Perhaps we can have an informal meet to discuss docs and Mathieu wrote: > I can manage to setup some place for those of you who will be there to > discuss all this. Whee. > All you have to do is to send me a mail to mathieu@advogato.org > with "GUADEC doc" as subject. -> when I know how much you'll be, > I'll manage to setup something. With nice Gnome T-shirts ? ;) I've already emailed, so Mathieu knows about one person, but just pour encourager les autres (although I'm not sure the thought of my running around grabbing people and demanding "Help, how do I..?" is encouraging), I think this is a great idea. Telsa From hobbit@aloss.ukuu.org.uk Thu May 11 23:31:00 2000 Received: (qmail 168 invoked from network); 31 Jan 2000 09:19:22 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 09:19:22 -0000 Received: from aloss.ukuu.org.uk (aloss.ukuu.org.uk [194.168.151.30]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id EAA24125 for ; Mon, 31 Jan 2000 04:19:18 -0500 Received: (from hobbit@localhost) by aloss.ukuu.org.uk (8.9.3/8.9.3) id JAA19042 for gnome-doc-list@gnome.org; Mon, 31 Jan 2000 09:18:36 GMT Date: Mon, 31 Jan 2000 09:18:36 +0000 From: Telsa Gwynne To: gnome-doc-list@gnome.org Subject: Re: The GNOME Handbook of Writing Software Documentation Message-ID: <20000131091836.C17462@aloss.ukuu.org.uk> Mail-Followup-To: gnome-doc-list@gnome.org References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: On Sun, Jan 30, 2000 at 09:16:13PM -0600 or thereabouts, Dan Mueth wrote: > > This weekend I started the GNOME Handbook of Writing Software ...and nearly finished :) > Documentation in CVS at gnome-docu/gdp/gdp-handbook.sgml. I also put it > on the web at http://www.gnome.org/gdp/gdp-handbook/. > Note that one section, "GDP Documentation Conventions" is meant to hold > all the numerous conventions the GDP decides upon, such as use of section > tags, formatting, use of SGML minimizations, etc. Presumably we can fill > this section in just by going through the mailing list archives. I think this is a really good idea. > Basics of Documentation Style - Any good writers among us who can tell us > all how to be good writers? I've seen some good resources recommended by technical writers; I'll dig 'em out of my bookmarks. > Telsa will be adding a section explaining how to write good DocBook. Haha. Let's clarify that a little :) Telsa will be adding a bit with a section with lots of words and concepts which can be marked up, and then have it marked up in bits, so that the first bit has all the screen markup stuff, another has all the "referring to other docs, sites, people" stuff, etc, and then the last one with the lot of them. The idea is that basically, I discovered I wasn't the only one who'd look at something and think, "I know there's a tag for this", and then have to hunt through about 300 tags, many of which were irrelevant. Grouping them together into clumps means someone can think, "this is a tag about a quote", look for the relevant section and find an example of the minimal details you need (like, say,

Blah blah

) and hopefully an example of it with all the optional bits in (like, say

Kubla KhanColeridge In Xanadu...

-- I'm picking this because it confused me no end that many things are and this one is foopoo without anything in quotes :)) This is pre-coffee so not making sense. Basically, when you have a paragraph with about twenty different things being used in it, it's hard to winnow out the example you want, but if you have four versions of the same one marked up partially and then a final version with all the markup integrated together, perhaps it will be clearer what fitted where. Then again, maybe not. Telsa From mathieu@mathieu.rezel.enst.fr Thu May 11 23:31:00 2000 Received: (qmail 14617 invoked from network); 31 Jan 2000 12:41:49 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 12:41:49 -0000 Received: from enst.enst.fr (enst.enst.fr [137.194.2.16]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id HAA30993 for ; Mon, 31 Jan 2000 07:41:44 -0500 Received: from email.enst.fr (muse.enst.fr [137.194.2.33]) by enst.enst.fr (8.9.1a/8.9.1) with ESMTP id NAA20276 for ; Mon, 31 Jan 2000 13:41:37 +0100 (MET) Received: from mathieu.rezel.enst.fr (mathieu.rezel.enst.fr [137.194.8.56]) by email.enst.fr (8.9.3/8.9.3) with ESMTP id NAA10677 for ; Mon, 31 Jan 2000 13:41:37 +0100 (MET) Received: from mathieu by mathieu.rezel.enst.fr with local (Exim 3.12 #1 (Debian)) id 12FLxn-0000GV-00; Mon, 31 Jan 2000 19:54:15 +0100 To: gnome-doc-list@gnome.org Subject: Re: The GNOME Handbook of Writing Software Documentation References: <20000131091836.C17462@aloss.ukuu.org.uk> Mime-Version: 1.0 (generated by tm-edit 7.106) Content-Type: text/plain; charset=US-ASCII From: lacage@email.enst.fr (Mathieu Lacage) Date: 31 Jan 2000 19:54:13 +0100 In-Reply-To: Telsa Gwynne's message of "Mon, 31 Jan 2000 09:18:36 +0000" Message-ID: <871z6yrs16.fsf@mathieu.rezel.enst.fr> Lines: 50 X-Mailer: Gnus v5.5/XEmacs 20.4 - "Emerald" Sender: Mathieu Lacage Telsa Gwynne writes: > Haha. Let's clarify that a little :) Telsa will be adding a bit > with a section with lots of words and concepts which can be marked up, > and then have it marked up in bits, so that the first bit has all > the screen markup stuff, another has all the "referring to other > docs, sites, people" stuff, etc, and then the last one with the > lot of them. The idea is that basically, I discovered I wasn't the > only one who'd look at something and think, "I know there's a tag > for this", and then have to hunt through about 300 tags, many of > which were irrelevant. Grouping them together into clumps means > someone can think, "this is a tag about a quote", look for the > relevant section and find an example of the minimal details you > need (like, say,

Blah blah

) and hopefully > an example of it with all the optional bits in (like, say >

Kubla KhanColeridge > In Xanadu...

-- I'm picking this because it confused me > no end that many things are and this one is > foopoo without > anything in quotes :)) > > This is pre-coffee so not making sense. Basically, when you have > a paragraph with about twenty different things being used in it, > it's hard to winnow out the example you want, but if you have four > versions of the same one marked up partially and then a final > version with all the markup integrated together, perhaps it will > be clearer what fitted where. > > Then again, maybe not. I like this idea a lot. I have found myself realizing I had missed a lot of useful tags when writing doc and getting back to what I had allready written to remark everything well... It's been a _real_ pain... This would allow me to have a good idea of all the useful tags and their use quickly. BTW: i remember the subject was brought someday but it is VERY important that the SGML minimization should be STRONGLY FORBIDDEN for any doc. I think that switching to XML is a not-so-far reachable goal (thanks to conglomerate.org) and minimization is exactly the kind of thing we want to avoid to make the switch not too painful. > > Telsa > regards, Mathieu From dcm@redhat.com Thu May 11 23:31:00 2000 Received: (qmail 26910 invoked from network); 31 Jan 2000 15:44:57 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 15:44:57 -0000 Received: from devserv.devel.redhat.com (root@devserv.devel.redhat.com [207.175.42.156]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id KAA10718 for ; Mon, 31 Jan 2000 10:44:56 -0500 Received: (from dcm@localhost) by devserv.devel.redhat.com (8.9.3/8.9.3) id KAA21206; Mon, 31 Jan 2000 10:44:31 -0500 Date: Mon, 31 Jan 2000 10:44:31 -0500 From: David Mason Message-Id: <200001311544.KAA21206@devserv.devel.redhat.com> To: lacage@email.enst.fr (Mathieu Lacage) Cc: gnome-doc-list@gnome.org Subject: (Was The GNOME Handbook of Writing Software Documentation) Now something else References: <20000131091836.C17462@aloss.ukuu.org.uk> <871z6yrs16.fsf@mathieu.rezel.enst.fr> X-URL: From: "David C. Mason" Date: 31 Jan 2000 10:44:31 -0500 Message-ID: Lines: 35 X-Mailer: Gnus v5.7/Emacs 20.5 lacage@email.enst.fr (Mathieu Lacage) writes: > BTW: i remember the subject was brought someday but it is VERY > important > that the SGML minimization should be STRONGLY FORBIDDEN for any doc. > > I think that switching to XML is a not-so-far reachable goal (thanks > to > conglomerate.org) and minimization is exactly the kind of thing we > want > to avoid to make the switch not too painful. But that has been my whole point to anyone who will listen - Graphical SGML Editors of this Nature(Conglomerate) make it too easy to minimize your markup!!!!!. It happen with every app that has taken this approach - it is way to easy to miss something like when all you have to do is write - not tag and write! I know people keep saying Conglomerate is the end all to our documentation woes - but it is not! From my tests of it - it does things a bit oddly (a stylesheet for a DTD to use *in* the editor only???) and it can make for badly marked up docs - have you seen the raw output? Thats why I was so disappointed to hear that the only thing even remotely related to docs at GUADEC was going to come from the GUADEC people - we aren't trying to build doc apps - we are trying to get people off their rear ends and write the docs that are so desperately needed if GNOME is ever going to be taken seriously! From dcm@redhat.com Thu May 11 23:31:00 2000 Received: (qmail 29802 invoked from network); 31 Jan 2000 15:50:49 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 15:50:49 -0000 Received: from devserv.devel.redhat.com (root@devserv.devel.redhat.com [207.175.42.156]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id KAA11056 for ; Mon, 31 Jan 2000 10:50:49 -0500 Received: (from dcm@localhost) by devserv.devel.redhat.com (8.9.3/8.9.3) id KAA21512; Mon, 31 Jan 2000 10:50:31 -0500 Date: Mon, 31 Jan 2000 10:50:31 -0500 From: David Mason Message-Id: <200001311550.KAA21512@devserv.devel.redhat.com> To: lacage@email.enst.fr (Mathieu Lacage) Cc: gnome-doc-list@gnome.org Subject: Re: (Was The GNOME Handbook of Writing Software Documentation) References: <200001311544.KAA21206@devserv.devel.redhat.com> X-URL: From: "David C. Mason" Date: 31 Jan 2000 10:50:31 -0500 Message-ID: Lines: 9 X-Mailer: Gnus v5.7/Emacs 20.5 > Thats why I was so disappointed to hear that the only thing even > remotely related to docs at GUADEC was going to come from the GUADEC > people I meant to say - "come from the Conglomerate people" Dave From mathieu@mathieu.rezel.enst.fr Thu May 11 23:31:00 2000 Received: (qmail 13747 invoked from network); 31 Jan 2000 16:03:11 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 16:03:11 -0000 Received: from enst.enst.fr (enst.enst.fr [137.194.2.16]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA11938 for ; Mon, 31 Jan 2000 11:03:06 -0500 Received: from email.enst.fr (muse.enst.fr [137.194.2.33]) by enst.enst.fr (8.9.1a/8.9.1) with ESMTP id RAA11526 for ; Mon, 31 Jan 2000 17:02:59 +0100 (MET) Received: from mathieu.rezel.enst.fr (mathieu.rezel.enst.fr [137.194.8.56]) by email.enst.fr (8.9.3/8.9.3) with ESMTP id RAA02452 for ; Mon, 31 Jan 2000 17:02:59 +0100 (MET) Received: from mathieu by mathieu.rezel.enst.fr with local (Exim 3.12 #1 (Debian)) id 12FP6g-0000KX-00; Mon, 31 Jan 2000 23:15:38 +0100 To: gnome-doc-list@gnome.org Subject: Re: (Was The GNOME Handbook of Writing Software Documentation) References: <200001311544.KAA21206@devserv.devel.redhat.com> Mime-Version: 1.0 (generated by tm-edit 7.106) Content-Type: text/plain; charset=US-ASCII From: lacage@email.enst.fr (Mathieu Lacage) Date: 31 Jan 2000 23:15:36 +0100 In-Reply-To: David Mason's message of "Mon, 31 Jan 2000 10:44:31 -0500" Message-ID: <87n1plopkn.fsf@mathieu.rezel.enst.fr> Lines: 62 X-Mailer: Gnus v5.5/XEmacs 20.4 - "Emerald" Sender: Mathieu Lacage David Mason writes: > Now something else > > > > > But that has been my whole point to anyone who will listen - > Graphical SGML Editors of this Nature(Conglomerate) > make it too easy to minimize your markup!!!!!. It What do you mean ? I don't understand this. I am sorry: GUI, especially the one which seems to be chosen by conglomerate (never tried it : just seen screenshots) is not obliged to allow you only to write and not structure. Such an application seems okay as it allows easy markup and visual feedback of the markup. However, you mentioned you tested it which I have not and you seem to say that it is not the case. Please, could you let us know why: if it is so, then the app needs to be improved. > happen with every app that has taken this approach - it is way to easy > to miss something like when all you have to do is write - > not tag and write! > > I know people keep saying Conglomerate is the end all to our > documentation woes - but it is not! From my tests of it - it does > things a bit oddly (a stylesheet for a DTD to use *in* the editor > only???) and it can make for badly marked up docs - have you seen the > raw output? well, I am sorry but I feel I miss your point. If you say that conglomerate output is bad, I take your word for it: conglomerate is simply bad and this has to be corrected. What I say is that : 1) we will need to switch to XML for our docs. 2) switching to XML has nothing to do with using GUI app to write docs. 3) GUI apps like conglomerate are expected to lower the level of knowledge users need to write doc. -> This is good. pause. This is good. I am myself not likely to write any doc using such a GUI because I like the Xemcs indentation of SGML/XML. > > Thats why I was so disappointed to hear that the only thing even > remotely related to docs at GUADEC was going to come from the GUADEC Yes, I am sorry for this and I regret it myself but the reasons for this are NOT because "we are trying to build doc apps". > people - we aren't trying to build doc apps - we are trying to get > people off their rear ends and write the docs that are so desperately > needed if GNOME is ever going to be taken seriously! > > Mathieu From dcm@redhat.com Thu May 11 23:31:00 2000 Received: (qmail 29438 invoked from network); 31 Jan 2000 16:50:33 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 16:50:33 -0000 Received: from chelseafc.labs.redhat.com (chelseafc.labs.redhat.com [207.175.42.116]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id LAA16384 for ; Mon, 31 Jan 2000 11:50:33 -0500 Received: (from dcm@localhost) by chelseafc.labs.redhat.com (8.9.3/8.9.3) id LAA15526; Mon, 31 Jan 2000 11:50:08 -0500 X-Authentication-Warning: chelseafc.labs.redhat.com: dcm set sender to dcm@redhat.com using -f To: lacage@email.enst.fr (Mathieu Lacage) Cc: gnome-doc-list@gnome.org Subject: Re: (Was The GNOME Handbook of Writing Software Documentation) References: <200001311544.KAA21206@devserv.devel.redhat.com> <87n1plopkn.fsf@mathieu.rezel.enst.fr> X-URL: From: "David C. Mason" Date: 31 Jan 2000 11:50:06 -0500 In-Reply-To: lacage@email.enst.fr's message of "31 Jan 2000 23:15:36 +0100" Message-ID: Lines: 93 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii lacage@email.enst.fr (Mathieu Lacage) writes: > I don't understand this. I am sorry: GUI, especially the one which seems > to be chosen by conglomerate (never tried it : just seen screenshots) > is not obliged to allow you only to write and not structure. > Such an application seems okay as it allows easy markup and visual > feedback of the markup. > > However, you mentioned you tested it which I have not and you seem to say > that it is not the case. Please, could you let us know why: if it is so, > then the app needs to be improved. When you are in the process of writing an sgml/xml doc in (for example) Emacs and you come across a word that needs to contain markup - you add the markup. Its all part of the process of your writing. If you use a GUI to do the document and you come across the word - you have to stop typing - grab the mouse - go through some menus - find the tag you want - and 'register' the word with the markup. Most people end up typing the whole thing and then going back to the beginning and searching for words that need markup. It (and the prime example would be people who use Adept's popular SGML GUI) tends to make people miss a lot of markup that they would normally have gotten if they had just written the SGML/XML to begin with. > well, I am sorry but I feel I miss your point. > > If you say that conglomerate output is bad, I take your word for it: > conglomerate is simply bad and this has to be corrected. > > What I say is that : > 1) we will need to switch to XML for our docs. > 2) switching to XML has nothing to do with using GUI app to write docs. > 3) GUI apps like conglomerate are expected to lower the level of knowledge > users need to write doc. -> This is good. pause. This is good. > > I am myself not likely to write any doc using such a GUI because > I like the Xemcs indentation of SGML/XML. Well your last line will answer one question - I like the indentation as well, but the output from Conglomerate does not indent - does not add returns - in fact, it has NO SPACES between words, phases, sentences, or paragraphs. It is a continuous stream of words that is incomprehensible when someone like you or I use Emacs to work on the doc. I agree we will need to switch to XML at some point - but I'm not sure we should do so until OASIS makes and official DocBook XML DTD - otherwise we could be using a buggy DTD. - The difference between the two so far is just the heading anyway - so it is likely we can process our SGML with and XML parser if we tell the parser to ignore the headers. What I'm really saying is - moving to XML will be the easiest thing we have to accomplish. I agree that a GUI doc app may help new people come aboard and start writing - and that is good, but if we get output like Conglomerate - those of us who will need to do things with those docs - like edit and change them, will be very frustrated. As I have said before, we can start getting new writers now by simply telling people that it is ok to submit their docs in ascii and those of us who know DocBook will mark it up for them - once they see their own docs returned in markup - they will start to learn and we will have more volunteers. > Yes, I am sorry for this and I regret it myself but the reasons for this > are NOT because "we are trying to build doc apps". I am not trying to blame you here - you have done a wonderful job in organizing the event - I am just worried that those who work hard everyday getting GNOME done do not realize that their masterpiece will lack such a fundamental feature as docs. They are working very hard to get to another release but their plans *never* include the time (and people) it will take to write the docs for all of these features. It is partly their fault, it is partly my fault, and it is a very big downside to the open source community in large. Cheers, Dave -- David Mason Red Hat AD Labs dcm@redhat.com From joakim@styx.net Thu May 11 23:31:01 2000 Received: (qmail 32627 invoked from network); 31 Jan 2000 17:03:40 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 17:03:40 -0000 Received: from relay1.mail.styx.net (nocto.styx.net [148.245.18.42]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA17743 for ; Mon, 31 Jan 2000 12:03:39 -0500 Received: from login1.styx.net (login1.styx.net [148.245.18.30]) by relay1.mail.styx.net (Postfix) with ESMTP id A8AE531009 for ; Mon, 31 Jan 2000 11:03:37 -0600 (CST) Received: by login1.styx.net (Postfix, from userid 5004) id 6A35F6C035; Mon, 31 Jan 2000 11:03:37 -0600 (CST) Date: Mon, 31 Jan 2000 11:03:37 -0600 From: Joakim Ziegler To: gnome-doc-list@gnome.org Subject: Re: (Was The GNOME Handbook of Writing Software Documentation) Message-ID: <20000131110337.E9219@styx.net> References: <200001311544.KAA21206@devserv.devel.redhat.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <200001311544.KAA21206@devserv.devel.redhat.com>; from dcm@redhat.com on Mon, Jan 31, 2000 at 10:44:31AM -0500 On Mon, Jan 31, 2000 at 10:44:31AM -0500, David Mason wrote: > But that has been my whole point to anyone who will listen - > Graphical SGML Editors of this Nature(Conglomerate) > make it too easy to minimize your markup!!!!!. It > happen with every app that has taken this approach - it is way to easy > to miss something like when all you have to do is write - > not tag and write! > I know people keep saying Conglomerate is the end all to our > documentation woes - but it is not! From my tests of it - it does > things a bit oddly (a stylesheet for a DTD to use *in* the editor > only???) and it can make for badly marked up docs - have you seen the > raw output? As duly noted in the release notes for that test code: If you're using Conglomerate to do any real work at this point, you are totally insane. The released Conglomerate code is a proof of concept, mostly for the GUI. Don't judge Conglomerate based on the current state of the output, that *will* be fixed. As for the stylesheet to be used only in the editor, yes, this is completely unavoidable if the we don't want a WYSIWYG XML editor, and although some people seem to think that this is a good idea (applying a presentation style sheet while you edit) we really want to avoid it, and show you the structure of what you're working on instead. The good news is that a) Conglomerate will ship with displayspecs for, amongst other things, DocBook, so you practically won't even notice that you require one, and b) there will be a dialog to easily change displayspecs while getting immediate feedback, so it's easy to set up your editing environment the way you like it. I might also add that if you have important feedback like this on problems with Conglomerate, it'd be really nice if the development team got to hear about it, instead of picking it up on a relatively unrelated mailing list. We are working very hard to try to create a high-quality document system, and this is certainly the type of concerns we'd appreciate to hear, it lets us do our job better. -- Joakim Ziegler - styx research director - joakim@styx.net FIX sysop - FIXmud admin - FIDEL & Conglomerate developer From joakim@styx.net Thu May 11 23:31:01 2000 Received: (qmail 7371 invoked from network); 31 Jan 2000 17:11:59 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 17:11:59 -0000 Received: from relay1.mail.styx.net (nocto.styx.net [148.245.18.42]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA18593 for ; Mon, 31 Jan 2000 12:11:58 -0500 Received: from login1.styx.net (login1.styx.net [148.245.18.30]) by relay1.mail.styx.net (Postfix) with ESMTP id 7BEA431016 for ; Mon, 31 Jan 2000 11:11:56 -0600 (CST) Received: by login1.styx.net (Postfix, from userid 5004) id 42AEA6C035; Mon, 31 Jan 2000 11:11:56 -0600 (CST) Date: Mon, 31 Jan 2000 11:11:56 -0600 From: Joakim Ziegler To: gnome-doc-list@gnome.org Subject: Re: (Was The GNOME Handbook of Writing Software Documentation) Message-ID: <20000131111156.F9219@styx.net> References: <200001311544.KAA21206@devserv.devel.redhat.com> <87n1plopkn.fsf@mathieu.rezel.enst.fr> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: ; from dcm@redhat.com on Mon, Jan 31, 2000 at 11:50:06AM -0500 On Mon, Jan 31, 2000 at 11:50:06AM -0500, David C. Mason wrote: > lacage@email.enst.fr (Mathieu Lacage) writes: >> I don't understand this. I am sorry: GUI, especially the one which seems >> to be chosen by conglomerate (never tried it : just seen screenshots) >> is not obliged to allow you only to write and not structure. >> Such an application seems okay as it allows easy markup and visual >> feedback of the markup. >> However, you mentioned you tested it which I have not and you seem to say >> that it is not the case. Please, could you let us know why: if it is so, >> then the app needs to be improved. > When you are in the process of writing an sgml/xml doc in (for > example) Emacs and you come across a word that needs to contain markup > - you add the markup. Its all part of the process of your writing. If > you use a GUI to do the document and you come across the word - you > have to stop typing - grab the mouse - go through some menus - find > the tag you want - and 'register' the word with the markup. Most > people end up typing the whole thing and then going back to the > beginning and searching for words that need markup. Conglomerate has hotkey support. At the moment, it only supports hotkey markup of things you select with the mouse, but this will change. We might emulate the Emacs way of doing it, or we might look at finding an even more efficient way, but getting the structured writing to be a 1-pass process is a concern, as is full mouseless operation. We write quite a lot of structured documents internally, and we know that there's a need for this. >> If you say that conglomerate output is bad, I take your word for it: >> conglomerate is simply bad and this has to be corrected. >> What I say is that : >> 1) we will need to switch to XML for our docs. >> 2) switching to XML has nothing to do with using GUI app to write docs. >> 3) GUI apps like conglomerate are expected to lower the level of knowledge >> users need to write doc. -> This is good. pause. This is good. >> I am myself not likely to write any doc using such a GUI because >> I like the Xemcs indentation of SGML/XML. > Well your last line will answer one question - I like the indentation > as well, but the output from Conglomerate does not indent - does not > add returns - in fact, it has NO SPACES between words, phases, > sentences, or paragraphs. It is a continuous stream of words that is > incomprehensible when someone like you or I use Emacs to work on the > doc. We are very aware of this. It's definitely on our list of things to fix. Please, don't judge the entire Conglomerate project on our release of a quick-and-dirty proof of concept pre-alpha. I'm a little dismayed at the tendency of people to regard things as writ in stone, even when we specifically said that it wasn't, that this is just to show to a certain degree how the GUI will work, etc. It seems this information wasn't heeded. Instead, tell us about all your concerns, and we will fix them before Conglomerate goes to 1.0. We're not some faceless corporation trying to develop a very closed system, we want and need your feedback (in particular on things we don't know about, of course, as opposed to this problem). I'm thinking the Conglomerate website might have room for a "Known bugs and fixes we plan to make before 1.0" page. -- Joakim Ziegler - styx research director - joakim@styx.net FIX sysop - FIXmud admin - FIDEL & Conglomerate developer From dcm@redhat.com Thu May 11 23:31:01 2000 Received: (qmail 15194 invoked by uid 504); 31 Jan 2000 17:29:42 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 15191 invoked from network); 31 Jan 2000 17:29:42 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 17:29:42 -0000 Received: from chelseafc.labs.redhat.com (chelseafc.labs.redhat.com [207.175.42.116]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id MAA20192 for ; Mon, 31 Jan 2000 12:29:42 -0500 Received: (from dcm@localhost) by chelseafc.labs.redhat.com (8.9.3/8.9.3) id MAA16557; Mon, 31 Jan 2000 12:29:26 -0500 X-Authentication-Warning: chelseafc.labs.redhat.com: dcm set sender to dcm@redhat.com using -f To: Joakim Ziegler cc: docs@gnome.org Subject: Re: (Was The GNOME Handbook of Writing Software Documentation) References: <200001311544.KAA21206@devserv.devel.redhat.com> <87n1plopkn.fsf@mathieu.rezel.enst.fr> <20000131111156.F9219@styx.net> X-URL: From: "David C. Mason" Date: 31 Jan 2000 12:29:26 -0500 In-Reply-To: Joakim Ziegler's message of "Mon, 31 Jan 2000 11:11:56 -0600" Message-ID: Lines: 61 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Joakim Ziegler writes: > Conglomerate has hotkey support. At the moment, it only supports hotkey > markup of things you select with the mouse, but this will change. We might > emulate the Emacs way of doing it, or we might look at finding an even more > efficient way, but getting the structured writing to be a 1-pass process is a > concern, as is full mouseless operation. We write quite a lot of structured > documents internally, and we know that there's a need for this. Well this sounds good - and I would love to hear/see more about it - so consider my comments here - a constructive comment on my opinions of GUI SGML/XML markup to date - not just what I saw of Conglomerate. > > Well your last line will answer one question - I like the indentation > > as well, but the output from Conglomerate does not indent - does not > > add returns - in fact, it has NO SPACES between words, phases, > > sentences, or paragraphs. It is a continuous stream of words that is > > incomprehensible when someone like you or I use Emacs to work on the > > doc. > > We are very aware of this. It's definitely on our list of things to fix. > Please, don't judge the entire Conglomerate project on our release of a > quick-and-dirty proof of concept pre-alpha. I'm a little dismayed at the > tendency of people to regard things as writ in stone, even when we > specifically said that it wasn't, that this is just to show to a certain > degree how the GUI will work, etc. It seems this information wasn't heeded. > > Instead, tell us about all your concerns, and we will fix them before > Conglomerate goes to 1.0. We're not some faceless corporation trying to > develop a very closed system, we want and need your feedback (in particular > on things we don't know about, of course, as opposed to this problem). Again - this was less about Conglomerate's early state and more about the GNOME community missing the point - we need docs damnit! Please take what I have said as official comments on my first impression - and feel free at any time to ask me what I think of an idea or ideas. I would love to see some of the things that apps like Adept got wrong - done right. I just have no idea how to do so and I hate contacting projects to complain without some sort of idea on how to fix it! > > I'm thinking the Conglomerate website might have room for a "Known bugs and > fixes we plan to make before 1.0" page. Good idea! Cheers, Dave -- David Mason Red Hat AD Labs dcm@redhat.com From steve@blah.dircon.co.uk Thu May 11 23:31:01 2000 Received: (qmail 28125 invoked from network); 31 Jan 2000 21:23:56 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 21:23:56 -0000 Received: from popmail.dircon.co.uk (popmail.dircon.co.uk [194.112.32.33]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id QAA07456 for ; Mon, 31 Jan 2000 16:23:56 -0500 Received: from blah.dircon.co.uk (blah.dircon.co.uk [194.112.43.123]) by popmail.dircon.co.uk with ESMTP id VAA19254 for ; Mon, 31 Jan 2000 21:23:54 GMT Received: by free.blah.dircon.co.uk via smail from stdin id (Debian Smail3.2.0.102) for ; Mon, 31 Jan 2000 21:34:43 +0000 (GMT) Received: from UNKNOWN(10.10.11.3), claiming to be "rat.blah.dircon.co.uk" via SMTP by free, id smtpda30718; Mon Jan 31 21:34:38 2000 Received: (from steve@localhost) by rat.blah.dircon.co.uk (8.9.3/8.8.7) id VAA19250 for gnome-doc-list@gnome.org; Mon, 31 Jan 2000 21:31:11 GMT Date: Mon, 31 Jan 2000 21:31:11 +0000 From: Steve George To: gnome-doc-list@gnome.org Subject: Re: folowup Message-ID: <20000131213111.A19230@rat.blah.dircon.co.uk> References: <87oga36v8p.fsf@mathieu.rezel.enst.fr> <20000131085943.B17462@aloss.ukuu.org.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <20000131085943.B17462@aloss.ukuu.org.uk>; from hobbit@aloss.ukuu.org.uk on Mon, Jan 31, 2000 at 08:59:43AM +0000 Reply_To: Steve George Hi, Well I shall be there also.......ooh T-shirt hopes :-) Anyone else? ... Any silent people who will be there speak now, unless your committed to being silent! Steve On Mon, Jan 31, 2000 at 08:59:43AM +0000, Telsa Gwynne wrote: > Steve wrote: > > > > Hopefully a few people from the GDP and Translations will be at GUADEC, > > > > I hope to be. Perhaps we can have an informal meet to discuss docs and > Mathieu wrote: > > I can manage to setup some place for those of you who will be there to > > discuss all this. > > Whee. > > > All you have to do is to send me a mail to mathieu@advogato.org > > with "GUADEC doc" as subject. -> when I know how much you'll be, > > I'll manage to setup something. With nice Gnome T-shirts ? ;) > > I've already emailed, so Mathieu knows about one person, but just > pour encourager les autres (although I'm not sure the thought of > my running around grabbing people and demanding "Help, how do I..?" > is encouraging), I think this is a great idea. > > Telsa > > > -- > FAQ: Frequently-Asked Questions at http://www.gnome.org/gnomefaq > To unsubscribe: mail gnome-doc-list-request@gnome.org with > "unsubscribe" as the Subject. > From dcm@redhat.com Thu May 11 23:31:01 2000 Received: (qmail 2332 invoked by uid 504); 31 Jan 2000 21:28:02 -0000 Delivered-To: gnome-docs@gnome.org Received: (qmail 2329 invoked from network); 31 Jan 2000 21:28:02 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 21:28:02 -0000 Received: from chelseafc.labs.redhat.com (chelseafc.labs.redhat.com [207.175.42.116]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id QAA07847 for ; Mon, 31 Jan 2000 16:28:01 -0500 Received: (from dcm@localhost) by chelseafc.labs.redhat.com (8.9.3/8.9.3) id QAA19101; Mon, 31 Jan 2000 16:27:46 -0500 X-Authentication-Warning: chelseafc.labs.redhat.com: dcm set sender to dcm@redhat.com using -f To: docs@gnome.org Subject: GNOME 2.0 Help System Update X-URL: From: "David C. Mason" Date: 31 Jan 2000 16:27:46 -0500 Message-ID: Lines: 63 User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii OK fellow GNOME writers.. here's the latest deal. Today jrb, Sopwith and I had a meeting about the GNOME Help System for GNOME 2.0 (please no "when is 2.0 coming out" questions - I don't know!). There are two major things to cover - the GNOME Help Browser and Context Sensitive Help. I'll start with Context Sensitive Help - this is pop-up help for those who know it by that name. The structure for getting this done is in place in the GNOME 2.0 libraries but there are some things Sopwith and I need to do before I can show you examples. First of all, the system works by the code having identification for widgets that will contain help. A Perl script will be run on the code to generate a "map" file. This file will allow the developer or writer to link widget ids to help topic ids. The help document is one big XML file that makes use of a very small set of tags (all of these tags are DocBook tags so you will not have to learn a new DTD). Each topic is defined by a - so you would have one large document that had a for each widget that has cs help. Since cs help should be very brief but descriptive - the documents should be relatively tame in size. What has to happen is that Sopwith and I need to decide how each tag will be handled (format-wise) as we are not using traditional parsers for this - this is all being done in gnome-libs. After that we will make a gnome-libs 2.0 branch that has cs help so you can all see it in action - I will also write an example, a template, a how-to, etc. OK - on to the Help Browser. The Browser was first going to be a separate entity until the Nautilus project started so I have less to report as this is very dependent on Nautilus. jrb is working on 'DocBook to Html on the fly' display right now for a couple of reasons - 1) downloading just sgml is smaller than sgml and html 2) searching on sgml is smarter. What do we lose? well we lose some formatting without dsssl but we gain valuable time not running jade. The plan is to replace this with Mozilla, DocBook XML, and XSL when they are all ready - so it is proactive planning in my opinion. jrb is also working on the search engine for this. It will be one of the first search engines I know of to take *real* advantage of SGML/XML content markup, but he will have to give more details when he gets further into it. Sopwith, jrb, and I all decided that *everyone* needs to discuss how an application is *registered* with the help browser though. Essentially we want the browser to know when you install GRandomApp so that it shows up in the TOC and search engine, etc. So put your thinking caps on and help us think about this one. Thats the state of the Help Union. -- David Mason Red Hat AD Labs dcm@redhat.com From jrb@aware-of-vacuity.labs.redhat.com Thu May 11 23:31:01 2000 Received: (qmail 31234 invoked from network); 31 Jan 2000 22:41:17 -0000 Received: from mail.redhat.com (199.183.24.239) by lists.redhat.com with SMTP; 31 Jan 2000 22:41:17 -0000 Received: from aware-of-vacuity.labs.redhat.com (root@aware-of-vacuity.labs.redhat.com [207.175.42.55]) by mail.redhat.com (8.8.7/8.8.7) with ESMTP id RAA13535 for ; Mon, 31 Jan 2000 17:41:17 -0500 Received: from localhost (IDENT:jrb@localhost [127.0.0.1]) by aware-of-vacuity.labs.redhat.com (8.9.3/8.9.3) with ESMTP id RAA16476; Mon, 31 Jan 2000 17:43:27 -0500 Message-Id: <200001312243.RAA16476@aware-of-vacuity.labs.redhat.com> To: "David C. Mason" Cc: gnome-doc-list@gnome.org From: jrb@redhat.com Reply-To: jrb@redhat.com Subject: Re: GNOME 2.0 Help System Update In-reply-to: Your message of "31 Jan 2000 16:27:46 EST." Date: Mon, 31 Jan 2000 17:43:26 -0500 Sender: jrb@aware-of-vacuity.labs.redhat.com > jrb is also working on the search engine for this. It will be one of > the first search engines I know of to take *real* advantage of > SGML/XML content markup, but he will have to give more details when he > gets further into it. I really like the idea of this in theory, but it needs a little more thought then just throwing a search-engine at docbook tags. Does anyone have any sort of experience in knowing what users search for? How do we want to index things? What particular tags are we looking for? We could certainly do some interesting meta searches (show me all help docs written by someone with "fred" in their name) but that's not what the user wants. Ideas??? (from anyone who knows docbook better) -Jonathan