Created attachment 56381 [details]
Archive containing patches and updated graphics

Contains patch, ChangeLog patch, screenshots... for nautilus documentation.

Created attachment 56389 [details]
Updated archive, the old one was wrong

With all that I managed to post a bad file, sorry, this should correct it.

Hello Karderio, 

I only take a quick look at the the screnshots, And I saw you didn't use the standard GNOME icon theme. 
Please for consistency, use the GNOME icon theme.

Thanks.

The lines 
<!-- Maintained for 2.8 compatibility -->
are to do with old ID tags.

AFAIK, they should be left as they are, rather than updated to read '2.13.3 compatibility'.
(see http://mail.gnome.org/archives/gnome-doc-list/2005-December/msg00097.html )

*** Bug 301406 has been marked as a duplicate of this bug. ***

*** Bug 314261 has been marked as a duplicate of this bug. ***

*** Bug 305857 has been marked as a duplicate of this bug. ***

*** Bug 324746 has been marked as a duplicate of this bug. ***

*** Bug 157507 has been marked as a duplicate of this bug. ***

Created attachment 56717 [details] [review]
latest patch for nautilus documentation in /gnome-user-docs/gnome2-user-guide/gosnautilus.xml

This is a work in progress, but the absence of this patch in CVS could block the fixing of bugs in Nautilus.

Thanks for your efforts!

You're really doing an important job! Maybe you could replace all occurences of "side pane" by "sidebar" in your draft?

Thanks for the encouragement, it's wondrous !

Nopb to replace "side pane" by "sidebar", thanks for the tip !

I have my little plan of updating the existing nautilus documentation, then documenting remaining functionality, then making everything consistent (there are outdated terms...), and finishing with a bit of polish. After I will patch nautilus so it goes where it should in the docs and includes help buttons where it can (i.e. places>connect to server), then looping over the rest of the unmaintained docs... When is 2.14 due out already :)

I hope I can at least get this done for the Nautilus docs, and have them translated into French for 2.14. I would set my sights a little further, but I am currently translating python.org to French and writing a book on programming with Python/GTK+.

Love, Karderio

It appears that 'side pane' is the recommended term in the GNOME Documentation Style Guide: http://developer.gnome.org/documents/style-guide/gnome-glossary-desktop.html

Following the "Style Guide" is nice, however, readability by the wider international audience may be desireable as well.

"Side pane" suggests an additional window while "Side bar" is the commonly used term for what we are talking about.

Readability is the continuing problem.

(In reply to comment #14)
> Following the "Style Guide" is nice, however, readability by the wider
> international audience may be desireable as well.
> 
> "Side pane" suggests an additional window while "Side bar" is the commonly used
> term for what we are talking about.

A pane is part of a window, in the original sense of a piece of glass, and in the sense of a computer application window.  (See http://en.wikipedia.org/wiki/Pane for more details.)  Of course the international audience must be accounted for, but at the same time, using accurate English verbiage is is a good thing.  A pane denotes a section of a window, and I'm not sure how it suggests otherwise.

Well, it's "side pane" in Nautilus, so I suppose it should be that in the docs also...

If not somebody should file a bug for the Style Guide.

The bugzilla calls it "sidebar", and I proposed to change all occurences of "side pane" in GConf key descriptions to "sidebar" (bug 131285). Epiphany also calls it sidebar.

Unfortunately, the feedback email address listed in the style guide (docs@gnome.org) doesn't have mailing list archives, and I can't find a style guide-related bugzilla product (cf. [1]).

[1] http://mail.gnome.org/archives/desktop-devel-list/2006-January/msg00028.html

Hmm, this is a mess. Long live consistency !

I think the subject deserves some discussion, it will not be too hard for me to change "side pane" to "sidebar" in the docs at the last minute, so I will wait for (Menubar)->Side Pane in Nautilus to be changed (if it gets changed) to avoid adding any more confusion.

I cannot find any way to file a bug against the style guide either, and this is probably not the only possible bug in there. I'm wondering if the same problem does not exist for much of the rest of the developer docs...

Love, Karderio

I agree with #18 -- we should maintain consistency within Nautilus, and follow the style guide until we update it. 

Christian: the style guide is here in CVS: /gnome-docu/gdp/style
Best place to raise the issue is the documentation list: http://mail.gnome.org/mailman/listinfo/gnome-doc-list/

As for bugzilla, we should maybe ask Shaun to add components to http://bugzilla.gnome.org/browse.cgi?product=gnome-user-docs 

A couple of things worth mentioning

1. This is not necessary; we can't change this every version

-  <!-- Maintained for 2.8 compatibility -->
+  <!-- Maintained for 2.13.3 compatibility -->

2. My "File Browser" entry is in Applications -> Accessories not "System Tools"
This just might be an Ubuntu specific thing.. ignore this if it is..

<para>Choose <menuchoice><guimenu>Applications</guimenu><guimenuitem>System Tools</guimenuitem><guimenuitem>File Browser</guimenuitem>

3. I seem to need to double click on the Home icon for it to change the view

+        <listitem>
+          <para>Click on the <guibutton>Home</guibutton> button in the Places side pane. </para>
+        </listitem>

4. (most important!) When removing sections that no longer apply, we need to put an anchor tag somewhere where it is appropriate or near a section that is closely related to the removed section (applications link to specific tags).  The form is    <anchor id="gosnautilus-<removed section number>"/>

This is important, please make sure you do this!

-    <sect2 id="gosnautilus-447">
...
-    <sect2 id="gosnautilus-445">
...
-      <sect3 id="gosnautilus-100">
...
etc...


I didn't have time to check the whole patch, but a lot of it is very good.  It would be great if you could deliver a single final patch that includes the changes to ChangeLog and gosnautilus.xml; cvs diff -u from the gnome-user-guide/ directory should do the trick.

Thanks again for your hard work.

Thanks for the tips :) I'm not sure I was aware of all of that, I will sort it out later. Here is a cut and paste from the gnome-doc-list to explain why it is still not very polished (to avoid too many people reading something that will change soon) :

This is a work in progress : many things are still missing, things need fixing, it has still not been proofread or spellechecked ; it is however more correct and more complete than the last two versions.

I have written a patch for nautilus to fix certain issues, but to avoid confusion I would like to only submit the patch after the documentation to which the user is sent to is correct and complete.

Love, Karderio

Re: #20:
"<!-- Maintained for 2.8 compatibility -->" doesn't mean "this document has been updated for Nautilus 2.8", it means "The following ID tag must be kept to maintain compatibility with 2.8". (See the link in comment #4.)
So yes, it should be left as is, not updated to read "2.13.3".
I suggest though we change the wording to something unambiguous: "ID tag preserved for 2.8 compatibility" for example.

Created attachment 56851 [details] [review]
New patch, resolving some compatibility problems - latest patch for nautilus documentation in /gnome-user-docs/gnome2-user-guide/gosnautilus.xml

Here is an update to the last patch adding (and only this to avoid confusion) references for obsolete sections.

<btw> Now that I have fixed the damage done by my great clodhoppers, is there anything stopping this from going into CVS ? Maybe all the problems that were mentioned in the bug are blocking, but there are many (many) more issues than this. Can it not be committed for now, and the problems will be fixed in a couple of weeks when I get a more final version out ? (I'm thinking along the lines that I had better get my fixes into Nautilus quick, or it will be too late for 2.14 : we will have help but no help buttons :-O )

<btw>Joachim, I agree with your rewording, I think I will just do that in the next version, I really can't see it bothering anyone in the slightest. (It will avoid newbies like me going through the whole documentation saying that it has been maintained for the latest version :)

Love, Karderio

Karderio: I will look at the patch again and see if it's ready to go into CVS

I got errors with the patch (shown at bottom).  The problem is there is an anchor tag that should be closed, i.e. <anchor id="..."> needs to be <anchor id="..."/>

The other problem is <sect3> tags at the beginning of the file that should be anchors

you should run the user-guide.xml file through "xmllint --valid user-guide.xml" when done to verify there are no errors in the file.

The other problem is there are two ids for gosnautilus-467, one at line 2555 and one at line 2582 (with patch applied).

The last problem is I don't understand why you add a new ID here
+    <sect2 id="gosnautilus-189">

Can you explain that?  If you can fix up these errors I don't see why we can't commit this...  I'll probably run it by nautilus maintainers (Manny) though first


smitten@home:/extra/cvs/gnome2/gnome-user-docs-head/gnome2-user-guide/C$ xmlstarlet sel -t -m '//@id' -v '.' -n user-guide.xml > after.txt
gosnautilus.xml:758: parser error : Opening and ending tag mismatch: anchor line 66 and sect1
  </sect1>
          ^
gosnautilus.xml:4012: parser error : Opening and ending tag mismatch: sect1 line 63 and chapter
</chapter>
          ^
gosnautilus.xml:4013: parser error : Premature end of data in tag sect3 line 31

^
gosnautilus.xml:4013: parser error : Premature end of data in tag sect3 line 29

^
gosnautilus.xml:4013: parser error : Premature end of data in tag sect3 line 27

^
gosnautilus.xml:4013: parser error : Premature end of data in tag anchor line 25

^
gosnautilus.xml:4013: parser error : Premature end of data in tag chapter line 1

^
gosnautilus.xml:4013: parser error : chunk is not well balanced

^
user-guide.xml:164: parser error : Failure to process entity gosnautilus
&gosnautilus;
             ^
user-guide.xml:164: parser error : Entity 'gosnautilus' not defined
&gosnautilus;
             ^

A doc update, great! But this bug belongs in the gnome-user-docs module I think. Also consider dropping a mail to gnome-doc-list@gnome.org about it.

Created attachment 57323 [details] [review]
updated patch

This patch fixes the above issues.
I have validated the user-guide with xmllint --valid and gosnautilus.xml does not give any errors (other files do, not the fault of this patch)

I have also verified all the ids have been preserved using xmlstarlet (one id has been added)

xml sel -t -m '//@id' -v '.' -n user-guide.xml | sort > beforepatch.txt
xml sel -t -m '//@id' -v '.' -n user-guide.xml | sort > afterpatch.txt
diff -u ~/beforepatch.txt ~/afterpatch.txt
--- /home/smitten/beforepatch.txt       2006-01-13 20:43:50.000000000 -0700
+++ /home/smitten/afterpatch.txt        2006-01-13 20:54:16.000000000 -0700
@@ -242,6 +242,7 @@
 gosnautilus-80
 gosnautilus-82
 gosnautilus-9
+gosnautilus-add-actions
 gosnautilus-FIG-504
 gosnautilus-FIG-505
 gosnautilus-TBL-10

I think the only thing left to do is get a maintainer from nautilus to look at the patch.  I have gone over a lot of it, and it removes a lot of old features like start-here:/// uris, etc.

Very sorry for the sloppy finish to that last patch, I hope I have finally learned my lesson to check things before posting them, thanks for fixing it Brent.

I hope to have a more or less final version to post for review by the end of the week, I'm not promising anything, but if I don't find any huge problems it is just about done.

Could somebody mark bug #139384 as a duplicate of this one please ?

Love, Karderio

*** Bug 139384 has been marked as a duplicate of this bug. ***

The bug 136779 - Insufficent docs for scripts - would be a duplicate of this bug, but I think it may already be fixed. However bug 125449 and bug 172206 that have been marked as a duplicate of this bug do not concern the documentation... I don't really know what to do : should bug 136779 be marked as closed, should it be marked as duplicate of bug 324966, are the two duplicate bugs marked incorrectly, or neither of the above ?

I think bug 133372 should be marked as closed if not it is at least a duplicate of this bug (324966).

Love, Karderio

*** Bug 136779 has been marked as a duplicate of this bug. ***

Created attachment 57746 [details] [review]
Latest patch to nautilus docs.

This is still not the final patch, I thought it better to post this now as Nautilus developers may be looking at this soon.

I've been over each chapter up to "Navigating Your Computer" (included) to assure that the docs are correct and that the main functionality is documented. The four last chapters remain to be given this treatment. I would then go over the whole thing and document any little bits of functionality that remain and then check that the English syntax conforms to the documentation guidelines.

Sorry not to have been able to get the final thing out before the end of the week, I promise any spare time to this.

Love, Karderio.

Created attachment 58665 [details] [review]
"Beta" patch to nautilus docs.

So, here is the "final-ish" patch.

I dare say that it covers most of the functionality, removes obsolete sections and corresponds to what is in the GUI.

I have merged content from the wiki, unfortunately I found that much of it was redundant :(

If anyone has the time, any comments would be much appreciated.

I have posted a few questions on the gnome-docs mailing list...

Love, Karderio

Created attachment 58710 [details] [review]
new version of the patch

Brent & I have reviewed this on IRC.
This version fixes a couple of duplicate ids.
IMO it can now be committed.

Excellent, milestoning to GNOME 2.14 so that it doesn't get lost. I'm setting the patch status to "none" since it wasn't yet reviewed, but I'm sure Shaun will accept it.

Created attachment 58713 [details] [review]
final patch 

ok here's the final one, with two slight fixes for duplicate ids, and one fix for a misplaced </sect3> tag.

Committed to HEAD.

Still need new figures, so I'm leaving this bug open until those get committed.

*** Bug 329070 has been marked as a duplicate of this bug. ***

Somehow I applied the wrong patch.

I have now applied the patch from comment 33 with some modifications:

* removed <releaseinfo> as this was causing validation errors
* second occurrence of gosnautilus-22 renamed to gosnautilus-presentation
* second occurrence of gosnautilus-493 renamed to gosnautilus-components
* second occurrence of gosnautilus-53 renamed to gosnautilus-components-view
* second occurrence of gosnautilus-101 renamed to gosnautilus-listview-arrange
* moved misplaced </sect3> tag
* second occurrence of gosnautilus-512 renamed to gosnautilus-templates-docs
* add <para> as child of <note> to fix validation
* second occurrence of gosnautilus-445 renamed to gosnautilus-install-scripts
* second occurrence of gosnautilus-445 renamed to gosnautilus-write-scripts
* removed authorgroup and revhistory and put them in the top-level document,
user-guide.xml

2006-02-11  Brent Smith  <gnome@nextreality.net>

        * gosnautilus.xml:
        Fix my error in applying wrong patch.
        * user-guide.xml:
        Added Karderio to the author listing, and modified the revhistory.


Still leaving this open due to the updated figures.

I just wanted to note that the images I uploaded to bug 314261 hasn't already been cvs added.

Nelson:

> I just wanted to note that the images I uploaded to bug 314261 hasn't already
been cvs added.

Thanks, good catch! I've committed them.

Brent:

> Still leaving this open due to the updated figures.

Did this only refer to the emblems, or are there other figures that require an update?

From comment 2 there are some updates to the following files:

naut_browser_window.png
naut_computer_contents.png
naut_home_launcher.png
naut_link_emblem.png
naut_noread_emblem.png
naut_nowrite_emblem.png

comment 3 noted that these files didn't use the correct icon theme, so I left the bug open.  It may be that these files have been updated recently, I will have to check when I have CVS access.

naut_browser_window.png - grep says no longer in the UG
naut_computer_contents.png - grep says no longer in the UG
naut_home_launcher.png - in gosdeskback.xml but this file is not used by the UG and needs to be removed anyway.

I've removed those files, thanks for your efforts Brent and Joachim! :) 

And thanks to Karderio too whose massive effort started this very long bug! :)

Yup, Kudos to Karderio! :)