Re: Documentation proofer

[boss <rick deb paradise net nz>]

Hi all.

I am new to all this but am available to proof read documentation if
anyone wants me too.

Regards

Richard Morris

On Wed, 2004-04-07 at 02:58, gnome-doc-list-request gnome org wrote:
> Send gnome-doc-list mailing list submissions to
> 	gnome-doc-list gnome org
> 
> To subscribe or unsubscribe via the World Wide Web, visit
> 	http://mail.gnome.org/mailman/listinfo/gnome-doc-list
> or, via email, send a message with subject or body 'help' to
> 	gnome-doc-list-request gnome org
> 
> You can reach the person managing the list at
> 	gnome-doc-list-admin gnome org
> 
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of gnome-doc-list digest..."
> 
> 
> Today's Topics:
> 
>    1. Re: Email viruses (Danilo Segan)
>    2. Re: Email viruses (Chris Lyttle)
>    3. Re: Contribution of Sun documentation team to the GDP. (Patrick Costello)
>    4. Re: Potential new documentation contributor (Matthew Revell)
>    5. Re: Potential new documentation contributor (Patrick Costello)
>    6. Re: Potential new documentation contributor (Matthew Revell)
>    7. Re: Potential new documentation contributor (Patrick Costello)
>    8. Re: Cantus 3 documentation (Alexander Kirillov)
>    9. Apostrophes (Matthew Revell)
>   10. Re: Potential new documentation contributor (Aaron Weber)
> 
> --__--__--
> 
> Message: 1
> To: gnome-doc-list gnome org
> Subject: Re: Email viruses
> From: Danilo Segan <danilo gnome org>
> Date: Mon, 05 Apr 2004 18:37:52 +0200
> 
> Today at 17:07, Telsa Gwynne wrote:
> 
> > So yes, if you know about that alias, it is effectively
> > open to anyone to post to. 
> 
> As it turns out, no.  Read below.
> 
> > However, to make things worse, lots of the virus-laden emails 
> > purport to come from people who are indeed subscribed to the 
> > mailing list. But they're not. The headers are forged. 
> 
> Ok, I've tested this and the problem here is *only* forging of "from"
> fields.  Alias is simply an alias which doesn't avoid moderation queue
> (I've just sent a message from unsubscribed address, and got notified
> that it got stuck in moderation queue; moderators, please disregard
> it, and sorry for wasting your time :).
> 
> So, the only problem with docs gnome org alias is that it is
> probably more exposed than the real list address.  Forged addresses
> cannot be coped with easily, unless we start doing something like
> requiring all messages to be signed or something.  And we're
> definitely not going to go that route.
> 
> So, I don't see a reason to dump this alias, since it's not really
> the problem.  Problems are forged mail headers which are used by
> spammers.
> 
> I know of two currently popular methods for handling this: virus/spam
> detectors on the server side, or on the client side.  I believe they
> do fairly good when set properly, but it would require more effort
> from already pre-occupied Gnome sysadmin team.
> 
> Cheers,
> Danilo
> 
> --__--__--
> 
> Message: 2
> Subject: Re: Email viruses
> From: Chris Lyttle <chris wilddev net>
> To: Danilo Segan <danilo gnome org>
> Cc: Gnome Doc list <gnome-doc-list gnome org>
> Date: Mon, 05 Apr 2004 20:28:20 -0700
> 
> I've had a similar problem here with my mailserver and
> amavisd/spamassassin/clamav quite nicely takes care of the virus
> problem.
> 
> Chris
> 
> PS We also implemented this on the GnuCash mailing lists which basically
> got rid of the virus problem :)
> 
> On Mon, 2004-04-05 at 09:37, Danilo Segan wrote:
> > Today at 17:07, Telsa Gwynne wrote:
> > 
> > > So yes, if you know about that alias, it is effectively
> > > open to anyone to post to. 
> > 
> > As it turns out, no.  Read below.
> > 
> > > However, to make things worse, lots of the virus-laden emails 
> > > purport to come from people who are indeed subscribed to the 
> > > mailing list. But they're not. The headers are forged. 
> > 
> > Ok, I've tested this and the problem here is *only* forging of "from"
> > fields.  Alias is simply an alias which doesn't avoid moderation queue
> > (I've just sent a message from unsubscribed address, and got notified
> > that it got stuck in moderation queue; moderators, please disregard
> > it, and sorry for wasting your time :).
> > 
> > So, the only problem with docs gnome org alias is that it is
> > probably more exposed than the real list address.  Forged addresses
> > cannot be coped with easily, unless we start doing something like
> > requiring all messages to be signed or something.  And we're
> > definitely not going to go that route.
> > 
> > So, I don't see a reason to dump this alias, since it's not really
> > the problem.  Problems are forged mail headers which are used by
> > spammers.
> > 
> > I know of two currently popular methods for handling this: virus/spam
> > detectors on the server side, or on the client side.  I believe they
> > do fairly good when set properly, but it would require more effort
> > from already pre-occupied Gnome sysadmin team.
> > 
> > Cheers,
> > Danilo
> > _______________________________________________
> > gnome-doc-list mailing list
> > gnome-doc-list gnome org
> > http://mail.gnome.org/mailman/listinfo/gnome-doc-list
> -- 
> RedHat Certified Engineer #807302549405490.
> Checkpoint Certified Security Expert 2000 & NG
> --------------------------------------------
> 	|^|
> 	| |   |^|
> 	| |^| | |  Life out here is raw 
> 	| | |^| |  But we will never stop
> 	| |_|_| |  We will never quit 
> 	| / __> |  cause we are Metallica
> 	|/ /    |
> 	\       /
> 	 |     |
> --------------------------------------------
> 
> 
> --__--__--
> 
> Message: 3
> Date: Tue, 06 Apr 2004 11:01:06 +0100
> From: Patrick Costello <Patrick Costello Sun COM>
> Subject: Re: Contribution of Sun documentation team to the GDP.
> To: Mark McLoughlin <mark skynet ie>
> Cc: GNOME Documentation List <gnome-doc-list gnome org>,
> 	Desktop Devel <desktop-devel-list gnome org>
> Reply-To: Patrick Costello Sun COM
> 
> Hi Mark, 
> 
> Thanks for taking an interest in documentation affairs, and thanks for
> taking the time to reply to my mail. See my inserts for some answers. 
> 
> Pat
> 
> Mark McLoughlin wrote:
> > 
> > Hi Pat,
> >         I do understand the pressures you guys are under and the problems you
> > face trying to maintain two different sets of documentation. I don't
> > want to seem like I'm underestimating those issues.
> > 
> >         However, I think a lot of the problems we're seeing here are largely
> > due to your lack of real understanding of how a community development
> > process works and the benefits of such a process. On the flip side, I
> > think the community has a lot of problems understanding *your*
> > development process and the benefits *you* see in following your
> > process. i.e. I put the problems largely down to a lack of communication
> > and understanding on both sides.
> > 
> 
> I really have to emphasize that our developing strategy is completely, and
> solely, driven by limited resources versus increasing workload. We have to
> reduce our commitments, otherwise we end up meeting neither Sun
> requirements nor GNOME community requirements. 
> 
> >         What I'd really like to see is a full, open and frank discussion on
> > figuring out a documentation development process that allows:
> > 
> >   + You guys to largely work from JDS yet still have your work be
> >     generally useful to the community.
> 
> We will put our JDS documentation back to the community, and this
> documentation could be useful for inclusion into future GNOME Desktop
> releases. But someone else will have to tailor our documentation to suit
> community needs. 
> 
> > 
> >   + Your work to be regularly updated in its final location in CVS, even
> >     if it is unfinished/un-reviewed (works-in-progress in CVS is a good
> >     thing)
> 
> Our standard process is to put back drafts at each review stage. However,
> do we really want to put back Sun-flavor documentation into the final
> location in CVS? 
> 
> > 
> >   + Other members of the documentation project contribute to the
> >     documentation
> 
> Absolutely. 
> 
> > 
> >   + The documentation in GNOME CVS to reflect as closely as possible the
> >     community's product - at least that it is possible for contributors
> >     to *bring* it up to date with the latest GNOME
> > 
> 
> Remember, we are working on a Desktop and applications one or two releases
> behind the current community release. That is causing us a big problem. For
> example, if we are working on a 2.2 level release for Sun, and the
> community is advancing to a 2.8 level release, what is really needed is for
> somebody to keep on working on the 2.8 level documentation. We can't do so
> much of that any more because of the resource constraint I mentioned above. 
> 
> >   + A greater level of communication and co-operation between everyone
> >     in the documentation project and hopefully a community atmosphere
> >     that would encourage more people to get involved
> > 
> 
> No amount of communication will alter the fact that we don't have enough
> resources in the Sun team to continue doing both Sun work and community
> work. No amount of cooperation will alter the version gap between Sun
> releases and community releases. No amount of community atmosphere will
> alter the design divergence between the Sun Desktop and the community
> Desktop. These are the things that are putting a strain on our small,
> overworked team. 
> 
> >         I hope you guys haven't decided for good that such a situation is
> > impossible.
> 
> We will still contribute whatever we work on. But we cannot continue to
> meet across-the-board commitments for the six-monthly community Desktop
> release cycle. It's killing us.
> 
> **********************************************
> Patrick Costello, GNOME Documentation
> Phone: 		01 819 9077 [ext 19077]
> **********************************************
> 
> --__--__--
> 
> Message: 4
> Date: Tue, 06 Apr 2004 11:34:12 +0100
> From: Matthew Revell <gdp-list understated co uk>
> To: gnome-doc-list gnome org
> Subject: Re: Potential new documentation contributor
> 
> Hi Aaron,
> 
> Aaron Weber wrote:
> 
> > Oh my goodness yes. For any web contributions, check with 
> > gnome-web-list gnome org <mailto:gnome-web-list gnome org>, or on the 
> > #gnome-hackers list. 
> 
> Thanks for that; I've subscribed to the list.
> 
> > I'm doing the Evolution docs, and would love feedback on those-- NNTP in 
> > particular is basically not done at all, and the S/MIME and security 
> > sections could use some work as well.
> 
> I'm more than happy to proof read the Evolution docs. What sort of time 
> frame are you working to?
> 
> Is there an editorial policy/style guide for Gnome docs? Or is there 
> anything else I could be reading up on?
> 
> -- 
> 
> Cheers,
> 
> Matthew Revell.
> 
> www.lugradio.org - radio for Linux and open source fans
> 
> --__--__--
> 
> Message: 5
> Date: Tue, 06 Apr 2004 11:55:13 +0100
> From: Patrick Costello <Patrick Costello Sun COM>
> Subject: Re: Potential new documentation contributor
> To: Matthew Revell <gdp-list understated co uk>
> Cc: gnome-doc-list gnome org
> Reply-To: Patrick Costello Sun COM
> 
> Hi Matthew, 
> 
> The GNOME Documentation Style Guide (GDSG) is at the following location: 
> 
> http://developer.gnome.org/documents/style-guide/
> 
> We update the terminology section of the GDSG regularly. 
> 
> Pat
> 
> 
> Matthew Revell wrote:
> > 
> > Hi Aaron,
> > 
> > Aaron Weber wrote:
> > 
> > > Oh my goodness yes. For any web contributions, check with
> > > gnome-web-list gnome org <mailto:gnome-web-list gnome org>, or on the
> > > #gnome-hackers list.
> > 
> > Thanks for that; I've subscribed to the list.
> > 
> > > I'm doing the Evolution docs, and would love feedback on those-- NNTP in
> > > particular is basically not done at all, and the S/MIME and security
> > > sections could use some work as well.
> > 
> > I'm more than happy to proof read the Evolution docs. What sort of time
> > frame are you working to?
> > 
> > Is there an editorial policy/style guide for Gnome docs? Or is there
> > anything else I could be reading up on?
> > 
> > --
> > 
> > Cheers,
> > 
> > Matthew Revell.
> > 
> > www.lugradio.org - radio for Linux and open source fans
> > _______________________________________________
> > gnome-doc-list mailing list
> > gnome-doc-list gnome org
> > http://mail.gnome.org/mailman/listinfo/gnome-doc-list
> 
> -- 
> **********************************************
> Patrick Costello, GNOME Documentation
> Phone: 		01 819 9077 [ext 19077]
> **********************************************
> 
> --__--__--
> 
> Message: 6
> Date: Tue, 06 Apr 2004 12:27:32 +0100
> From: Matthew Revell <gnome understated co uk>
> To: gnome-doc-list gnome org
> Subject: Re: Potential new documentation contributor
> 
> Hi Pat,
> 
> Patrick Costello wrote:
> 
> >The GNOME Documentation Style Guide (GDSG) is at the following location: 
> >  
> >
> Thanks for that.
> 
> Is there a document that describes Sun's relationship with the Gnome 
> documentation project? I've seen a couple of emails on the list about 
> it, but I've also noticed that the Gnome docs and style guide are 
> copyright Sun.
> 
> -- 
> 
> Cheers,
> 
> Matthew Revell.
> 
> www.lugradio.org - radio for Linux and open source fans
> 
> 
> --__--__--
> 
> Message: 7
> Date: Tue, 06 Apr 2004 12:41:42 +0100
> From: Patrick Costello <Patrick Costello Sun COM>
> Subject: Re: Potential new documentation contributor
> To: Matthew Revell <gnome understated co uk>
> Cc: gnome-doc-list gnome org
> Reply-To: Patrick Costello Sun COM
> 
> Matthew Revell wrote:
> > 
> > Hi Pat,
> > 
> > Patrick Costello wrote:
> > 
> > >The GNOME Documentation Style Guide (GDSG) is at the following location:
> > >
> > >
> > Thanks for that.
> > 
> > Is there a document that describes Sun's relationship with the Gnome
> > documentation project? I've seen a couple of emails on the list about
> > it, but I've also noticed that the Gnome docs and style guide are
> > copyright Sun.
> > 
> 
> The relationship of Sun with the GNOME community is exactly the same as the
> relationship of any other contributor and is defined under the general
> rules of free software development. 
> 
> If you see "Sun Microsystems" in a copyright line on a GNOME manual, then
> all that means is that Sun Microsystems is one of the contributors to the
> manual. As GNOME manuals are published under the GNU Free Documentation
> License (GFDL), this does not mean that the Sun copyright is an exclusive
> copyright. If you update a manual that Sun did this time around, then
> "Copyright 2004: Matthew Revell" will appear in the copyright list above
> the Sun copyright. That's how it works. When someone within Sun does a job,
> we assign the copyright to Sun, rather than the individual, as the work
> that Sun employees do belongs to Sun, not to individuals. 
> 
> I hope that clears up any questions you had in this regard. 
> 
> Pat
> ______________________________________________
> > gnome-doc-list mailing list
> > gnome-doc-list gnome org
> > http://mail.gnome.org/mailman/listinfo/gnome-doc-list
> 
> -- 
> **********************************************
> Patrick Costello, GNOME Documentation
> Phone: 		01 819 9077 [ext 19077]
> **********************************************
> 
> --__--__--
> 
> Message: 8
> Subject: Re: Cantus 3 documentation
> From: Alexander Kirillov <kirillov math sunysb edu>
> To: Samuel Abels <spam debain org>
> Cc: GNOME Doc List <gnome-doc-list gnome org>
> Date: Tue, 06 Apr 2004 09:10:38 -0400
> 
> No, TeX - much as I like it - is not the correct format for online
> documentation. The format used by GNOME docs is DocBook 4.1.2 (it takes
> some time to learn, though). 
> 
> I can convert your document into DocBook - this is not hard. It would do
> for a start. For future use, the manual will need a lot more detail -
> but I can't help here as I do not have Cantus installed yet. Once I
> have, I could give you a hand with this. 
> 
> Best,
> Sasha
> 
> 
> On Mon, 2004-04-05 at 05:13, Samuel Abels wrote:
> > Hello,
> > 
> > In preparation of the Cantus 3 final release with closer GNOME
> > integration I have prepared a simple End User Documentation. Anyway, I
> > am not a native english speaker, so the result is probably unsatisfying.
> > 
> > Talking to the desktop-devel-list for GNOME2.8 preparation I have been
> > asked to check the documentation with you guys, so I would be happy to
> > receive your comments.
> > 
> > I have appended the documentation as a .tex document; I hope that is the
> > right format. Please let me know if it is not.
> > 
> > The project homepage ist here:
> > http://www.debain.org/?project=3
> > 
> > A second question: Is proper API documentation also required for GNOME
> > inclusion? In that case, I would appreciate your comments on it also:
> > 
> > http://www.debain.org/cantus/cantus3_api.html
> > 
> > -Samuel
> > 
> > -----------------------------------------------
> > \documentclass{article}
> > \title{Cantus 3}
> > \author{Samuel Abels}
> > \date{February 2004}
> > \begin{document}
> > \maketitle
> > \tableofcontents
> > % --------------------------------------------------------------
> > \section{Indroduction}
> >   \subsection{What is Cantus?}
> >   Cantus is an easy to use Tag Editor, primarily made to tag Audio files.
> >   
> > % --------------------------------------------------------------
> > \section{The Mainwindow}
> >   The mainwindow consists of basicly two elements:
> >   
> >   \begin{itemize}
> >   \item  The filebrowser in the middle of the window, consisting of a directory
> >          tree on the left side and filelist on the right side.
> >   \item  The toolarea, on the bottom of the window.
> >   \end{itemize}
> >   
> >   The toolarea can also be shown on the right of the window. Refer to
> >   \ref{mainwindow:menus}Menus.
> >   
> > \subsection{Menus}
> > \label{mainwindow:menus}
> >   The "File" menu has currently only one item: "Quit" exits the program
> >   immidiately.
> >   
> >   The "Edit" menu provides "Cut", "Copy" and "Paste" to lets you do clipboard
> >   operations with any selected text. By clicking on "Preferences", the
> >   Preferences dialog will be opened.
> >   
> >   The "View" menu lets you change the window appearance. You can choose the
> >   position of the Tools, eighter right or bottom.
> >   
> > \subsection{Viewing Tags}
> >   Use the directory browser in the mainwindow to navigate to the directory
> >   containing the files you want to view.
> >   By clicking on the directory the filelist will show your files up.
> >   If it does not, you might want to look at section \ref{pref:filebrowser}
> >   File Browser Preferences.
> >   
> >   Then, mark the file whose tag you want to view by clicking on it. When you
> >   do, the pluginarea will show up, showing all informations regarding the tags
> >   of the chosen file.
> >   
> >   Once you have selected a file and the tools have become visible, select a
> >   tool by clicking on its tab label. For example, click on "ID3V2 Tag" to
> >   edit the tag fields.
> >   
> >   The current tag of the file shows up.
> >   
> > \subsection{Writing Tags}
> >   Once you have opened a file and view the tag in a tool, you can edit its tag
> >   fields. For example, enter "My superb Artist" in the "Artist" entry box.
> >   To mark the field for writing, activate the check box right from the entry
> >   box.
> >   
> >   Repeat the above procedure for every field that you want to change.
> >   
> >   When ready, click "Save" and the tag will be written to all files that are
> >   currently selected in the filebrowser.
> >   All fields that do not have the checkbox activated will be left untouched.
> >   
> > \section{Preferences}
> >   The preferences dialog lets you customize Cantus to fit your needs.
> >   
> > \subsection{File Browser Preferences}
> > \label{pref:filebrowser}
> >   You can customize the File Browser appearance in this section of the
> >   preferences dialog.
> >   
> >   The "Startup Directory" is the directory that Cantus will open immidiately
> >   after program startup.
> >   If the startup directory can not be found, your home directory will be opened.
> >   If your home directory can not be found, the filesystem root will be opened.
> >   
> >   The "Show filetypes" lets you specify all filetypes that you consider being
> >   of interest for you. You can enter glob-style patterns there. For example,
> >   to display .ogg files only, enter "*.ogg".
> >   To display .ogg and .flac files as well, enter "*.ogg,*.flac".
> >   
> >   By activating the "Show hidden files" checkbox you indicate Cantus not to
> >   skip files beginning with a dot (".").
> >   
> > % --------------------------------------------------------------
> > \section{About this Document}
> > Written by Samuel Abels. Please refer comments to the author.
> > 
> > Current Revision: 1.0
> > \end{document}
> > 
> > _______________________________________________
> > gnome-doc-list mailing list
> > gnome-doc-list gnome org
> > http://mail.gnome.org/mailman/listinfo/gnome-doc-list
> 
> 
> --__--__--
> 
> Message: 9
> Date: Tue, 06 Apr 2004 15:45:11 +0100
> From: Matthew Revell <gnome understated co uk>
> To: gnome-doc-list gnome org
> Subject: Apostrophes
> 
> Howdy all,
> 
> I'm reading through the GNOME Documentation Style Guide V1.3 and have a 
> question, regarding apostrophe usage.
> 
> On the page titled"Grammar and Usage Guidelines", there is an entry, 
> which reads:
> 
> "Apostrophe
> 
> Rules
> 
> * Do not use apostrophes to denote possession.
> * Do not use apostrophes to denote contractions.
> * Do not use apostrophes to denote plurals."
> 
> The last of these I can agree with, but I'm a little confused by the 
> first two. Are they a mistake?