Last Comment Bug 226191 - Fix filenames for mozilla help to follow readme-style
: Fix filenames for mozilla help to follow readme-style
Status: RESOLVED FIXED
:
Product: SeaMonkey
Classification: Client Software
Component: Help Documentation (show other bugs)
: Trunk
: All All
: -- normal (vote)
: seamonkey2.1a2
Assigned To: [:rickiees] Ricardo Palomares
:
:
Mentors:
http://www.mozilla.org/README-style.h...
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2003-11-19 03:29 PST by timeless
Modified: 2010-06-01 15:27 PDT (History)
7 users (show)
See Also:
Crash Signature:
(edit)
QA Whiteboard:
Iteration: ---
Points: ---


Attachments
First try to fix filenames to use underscore instead of hyphen [Checkin: Comment 18] (13.87 KB, patch)
2010-05-31 12:13 PDT, [:rickiees] Ricardo Palomares
iann_bugzilla: review+
Details | Diff | Splinter Review

Description timeless 2003-11-19 03:29:41 PST
I was reviewing a patch for rjk and noticed that help uses both - and _ in
filenames. This sucks :). I said that I thought we should only use -, I was
right. Please fix.
Comment 1 R.J. Keller 2003-11-19 04:27:48 PST
Accepting
Comment 2 Daniel Wang 2003-11-19 09:13:39 PST
Keller, can we hold this? After we update and convert all files to .xhtml , we
should start reorganizing and breaking up the content into smaller files. Then
we can fix the filenames.
Comment 3 R.J. Keller 2003-11-19 14:41:26 PST
of course, I was thinking the same thing.
Comment 4 Robert Kaiser 2009-06-14 17:40:47 PDT
MASS-CHANGE:
This bug report is registered in the SeaMonkey product, but has been without a comment since the inception of the SeaMonkey project. This means that it was logged against the old Mozilla suite and we cannot determine that it's still valid for the current SeaMonkey suite. Because of this, we are setting it to an UNCONFIRMED state.

If you can confirm that this report still applies to current SeaMonkey 2.x nightly builds, please set it back to the NEW state along with a comment on how you reproduced it on what Build ID, or if it's an enhancement request, why it's still worth implementing and in what way.
If you can confirm that the report doesn't apply to current SeaMonkey 2.x nightly builds, please set it to the appropriate RESOLVED state (WORKSFORME, INVALID, WONTFIX, or similar).
If no action happens within the next few months, we move this bug report to an EXPIRED state.

Query tag for this change: mass-UNCONFIRM-20090614
Comment 5 Ian Neal 2010-05-18 05:52:17 PDT
The files we need to worry about are:
shortcuts-composer.xhtml
shortcuts-mailnews.xhtml
shortcuts-navigator.xhtml
The rest can wait until bug 130733 is fixed.
Comment 6 [:rickiees] Ricardo Palomares 2010-05-31 11:08:37 PDT
Based on comment 5, fixing this seems almost trivial. Apparently, only four files contain the sequence "shortcuts-" (in comm-central):

shortcuts.xhtml
help-index1.rdf
suite-toc.rdf
customize_help.xhtml

Is it OK if give it a try?
Comment 7 Ian Neal 2010-05-31 11:51:58 PDT
Yes, please. Don't forget /suite/locales/jar.mn
Use hg rename to keep the history of the shortcut-* files
Comment 8 [:rickiees] Ricardo Palomares 2010-05-31 12:13:40 PDT
Created attachment 448411 [details] [diff] [review]
First try to fix filenames to use underscore instead of hyphen [Checkin: Comment 18]

Providing patch and taking the bug myself.
Comment 9 [:rickiees] Ricardo Palomares 2010-05-31 12:19:39 PDT
Actually, I've just read mozilla.org Documentation Style (the URL referenced in the bug) and I think I've done it the reverse of how it should be, because I've extended the use of underscores instead of removing them in favor of hyphens. :-? The truth is that use of underscore is dominant in help files, but I don't know if that's the case for the generality of mozilla.org repository.

Besides that, there are some files in help/images that use hyphens whereas most use underscore.
Comment 10 Jens Hatlak (:InvisibleSmiley) 2010-05-31 12:50:03 PDT
(In reply to comment #9)
> Actually, I've just read mozilla.org Documentation Style (the URL referenced in
> the bug) and I think I've done it the reverse of how it should be, because I've
> extended the use of underscores instead of removing them in favor of hyphens.

Right, according to that document and the previous comments in this bug (with the notable exception of Ian's comment 5 which got it wrong in the first place), the hyphen should be used throughout the help/ directory.

However:
1. Most files in help/ use the underscore to separate words in the file name.
2. I think the reasoning for using hyphens, which is given in the document (URL), does not apply to Help. Help links use custom link labels (is that the correct term?) instead of the name of the target file (correct me if I'm wrong).

> The truth is that use of underscore is dominant in help files, but I don't
> know if that's the case for the generality of mozilla.org repository.

I'd say the rest of the repository (or even others) is irrelevant, Help is pretty self-contained.

> Besides that, there are some files in help/images that use hyphens whereas most
> use underscore.

Well, I'm not sure starting to clean up there is worth the effort. Ian may think differently, though.

BTW: Feel free to CC me to any bugs you comment or start working on. Likewise for attachment review or feedback requests. ;-)
Comment 11 Ian Neal 2010-05-31 13:10:33 PDT
Hmmm, not sure how I got confused, but Jens is correct.
It is best we are consistent but as Jens said, is it worth the effort.
Yes, it would be nice to have all files using hyphen instead of underscore, but I rather effort goes into fixing help content than fixing filenames.
Any new files created or major work carried out on content should correct filenames but doing it one single patch would be too much work (both on patch generation and on reviewing).
Comment 12 Jens Hatlak (:InvisibleSmiley) 2010-05-31 13:20:53 PDT
Well, maybe I wasn't clear enough: I actually think we could take Ricardo's patch even if it contradicts the document linked in this bug and the previous comments, effectively changing all help files to match the current/de facto underscore rule. The reason for hyphenation given in the document was "underscores don't show up in underlined text" but we don't show those file names anywhere, do we?

Also my "worth the effort" comment was with respect to the image file names, not the XHTML files.
Comment 13 [:rickiees] Ricardo Palomares 2010-05-31 13:26:38 PDT
I actually think both of you are saying basically the same thing. I also humbly the effort to provide a "_" -> "-" patch is too big for the win.
Comment 14 Ian Neal 2010-05-31 13:51:31 PDT
Comment on attachment 448411 [details] [diff] [review]
First try to fix filenames to use underscore instead of hyphen [Checkin: Comment 18]

r=me
Comment 15 [:rickiees] Ricardo Palomares 2010-06-01 01:01:17 PDT
(In reply to comment #14)
> (From update of attachment 448411 [details] [diff] [review])
> r=me


Could you also land the patch, please? I don't have commit rights to comm-central. :-)
Comment 16 Jens Hatlak (:InvisibleSmiley) 2010-06-01 04:38:11 PDT
(In reply to comment #15)
> Could you also land the patch, please? I don't have commit rights to
> comm-central. :-)

Just set the checkin-needed keyword and one of us will take care of that "automatically".
Comment 17 [:rickiees] Ricardo Palomares 2010-06-01 04:54:13 PDT
(In reply to comment #16)
> (In reply to comment #15)
> > Could you also land the patch, please? I don't have commit rights to
> > comm-central. :-)
> 
> Just set the checkin-needed keyword and one of us will take care of that
> "automatically".


Sorry, it has been a long time since I last contributed a patch and I've forgotten the procedure. :-) Done, thank you for reminding me.
Comment 18 Ian Neal 2010-06-01 05:49:01 PDT
Comment on attachment 448411 [details] [diff] [review]
First try to fix filenames to use underscore instead of hyphen [Checkin: Comment 18]

http://hg.mozilla.org/comm-central/rev/7f5ea53dcf38
Comment 19 Ian Neal 2010-06-01 05:49:31 PDT
Thanks for the patch :)
Comment 20 fantasai 2010-06-01 15:27:36 PDT
In case you want to do something like this in the future, doing a mass-rename of files would be pretty easy with this tool: http://fantasai.inkedblade.net/tools/about-xre
  xre 'hg rename' 's/_/-/g' *

Fixing up links in the source would be something like
  perl -pi -e '$/ = '>'; if (m/(href|src|data)="([^:]+)"/) { $uri = $2; $uri =~ tr/_/-/; s/$1="$2"/$1="$uri"/; }' *
The first statement causes Perl to split the file on '>' instead of '\n'.
The second greps for URIs.
The third and fourth create the new URI.
The fifth does the actual substitution.

Note You need to log in before you can comment on or make changes to this bug.