274417 - Cleanup www.mozilla.org/directory

Status: RESOLVED FIXED

(www.mozilla.org :: General, defect)

Description

[Simon Paquet [:sipaq]]

The HTML code in http://www.mozilla.org/directory/ is a huge mess, especially in
http://www.mozilla.org/directory/csdk-docs/ - There are all kinds of '<a
name="123"></a>' constructs which should be replaced with valid ID attributes on
the appropriate elements as in '<h3 id="n-123">foo</h3>'. Most of these internal
links aren't needed anyway.

I've already tried to tackle most of this. Most of the csdk-docs-directory has
already been cleaned up. The following files in that directory are still in need
of cleanup:

- addmod.htm
- datatype.htm
- filter.htm
- function.htm

The rest of www.mozilla.org/directory has already been tackled in small parts.

Comment 1

[Anne (:annevk)]

I thought we had a bug about this, apparently not. Anyway, instead of having
numbers, fantasai suggested, for a similar situation, to drop the numbers and
use useful ID attribute values instead. Like |<h3 id="foo">foo</h3>| or |<h3
id="foo-bar">foo bar</h3>| or |<h3 id="foo-bar">Foo bar</h3>|, et cetera. (Same
guidelines as for URIs apply: lowercase, hyphens.)

Comment 2

[Anne (:annevk)]

By the way, thanks for the all the work!

We also want to use |<ul class="snav">| instead of a P element and the relevant
LINK elements. We also don't want to point to 'index.htm' but to './'. For an
example see <http://www.mozilla.org/directory/csdk-docs/search.htm>.

Eventually we might want to drop file extensions using MultiViews and I guess
fantasai would like the file extensions to be .html.

Comment 3

[Simon Paquet [:sipaq]]

(In reply to comment #1)
> I thought we had a bug about this, apparently not. Anyway, instead of having
> numbers, fantasai suggested, for a similar situation, to drop the numbers and
> use useful ID attribute values instead. Like |<h3 id="foo">foo</h3>| or |<h3
> id="foo-bar">foo bar</h3>| or |<h3 id="foo-bar">Foo bar</h3>|, et cetera. (Same
> guidelines as for URIs apply: lowercase, hyphens.)

Yep, 
but I reserve this task for a later time, because I want all the files to be in
a usable state, before someone can tackle this.

Comment 4

[Simon Paquet [:sipaq]]

(In reply to comment #2) 
> We also want to use |<ul class="snav">| instead of a P element and the relevant
> LINK elements. We also don't want to point to 'index.htm' but to './'. For an
> example see <http://www.mozilla.org/directory/csdk-docs/search.htm>.

Done.

> Eventually we might want to drop file extensions using MultiViews 

???
Sorry, could you clarify this? I might be dumb, but what are MultiViews?

> and I guess fantasai would like the file extensions to be .html.

Yep, but IMO that's only a aesthetical problem.

Comment 5

[fantasai]

Unless we're moving the files around anyway, or they're certainly at the
location they'd be if we were free to move them around, we probably shouldn't
just drop or change the file extension for the sake of doing so.

Comment 6

[Simon Paquet [:sipaq]]

Ok, I fixed up pretty much everything major in all the sub-directories except
the csdk-docs directory. The following files still need a cleanup:

In the main directory:
- addrbook-refactoring-proposal.html
- csdk-tests.html
- java40betarelnotes.html
- java41relnotes.html

In the csdk-docs directory:
- See comment 0.

Comment 7

[Mark Smith [:mcs]]

The files under csdk-docs were generated from FrameMaker originally (which
explains the name="123" constructs; I think that is how Frame handles
cross-references).

Comment 8

[Simon Paquet [:sipaq]]

(In reply to comment #0)
> Most of the csdk-docs-directory has already been cleaned up. The following 
> files in that directory are still in need of cleanup:
> 
> - addmod.htm
> - datatype.htm
> - filter.htm
> - function.htm

addmod.htm has just been cleaned up. Only the last three files are still
outstanding. Volunteers welcome ;-)

Comment 9

[Anne (:annevk)]

I did some general clean up in some files and I'm now working on 'datatype.htm'.
However, we still need to fix the NAME/ID issue mentioned in comment 1.

Comment 10

[Anne (:annevk)]

Besides changing the ID attributes, I think we should consider changing the H1
as well. IMHO H1 should be the title of the page, not the title of a serie of
documents. Perhaps we could drop the current H1 element (and leave the
information inside TITLE) and make the chapter titles H1?

datatype.htm is done by the way.

Comment 11

[Simon Paquet [:sipaq]]

filter.htm is also done.

I've cleaned up 20-25% of function.htm. I hope to finish this by the end of the
year.

Comment 12

[Simon Paquet [:sipaq]]

Short update:
function.htm, the last outstanding file for the general cleanup of the csdk-docs
is 90% finished. I hope to commit this in the next few days. The size reduction
of that file is huge.

Before cleanup: ca. 1380 KB
After cleanup: ca. 540 KB

Comment 13

[Simon Paquet [:sipaq]]

The new version of function.htm has been checked in.

Comment 14

[Simon Paquet [:sipaq]]

(In reply to comment #6)
> Ok, I fixed up pretty much everything major in all the sub-directories except
> the csdk-docs directory. The following files still need a cleanup:
> 
> In the main directory:
> - addrbook-refactoring-proposal.html
> - csdk-tests.html
> - java40betarelnotes.html
> - java41relnotes.html

The first two documents have been cleaned up. Both validate now.

Comment 15

[Simon Paquet [:sipaq]]

(In reply to comment #6)
> Ok, I fixed up pretty much everything major in all the sub-directories except
> the csdk-docs directory. The following files still need a cleanup:
> 
> In the main directory:
> - java40betarelnotes.html

This one has also been cleaned up and validates now.

Comment 16

[Simon Paquet [:sipaq]]

(In reply to comment #1)
> Anyway, instead of having numbers, fantasai suggested, for a similar situation, 
> to drop the numbers and use useful ID attribute values instead. Like 
> |<h3 id="foo">foo</h3>| or |<h3 > id="foo-bar">foo bar</h3>| or 
> |<h3 id="foo-bar">Foo bar</h3>|, et cetera.

Anne, after fixing the only outstanding file that doesn't validate
<http://www.mozilla.org/directory/java41relnotes.html>, I would like to mark
this bug as FIXED and move the work you describe in your comment into a new bug.
IMO this doesn't fall into the scope of general cleanup and validation work.

What do you think?

Comment 17

[Anne (:annevk)]

I'm ok with the new bug.

Comment 18

[Simon Paquet [:sipaq]]

Ok, I fixed the last remaining file. Thanks a lot for all the help.
I will file a new bug for the stuff mentioned in comment 16.

Comment 19

[Simon Paquet [:sipaq]]

(In reply to comment #18)
> I will file a new bug for the stuff mentioned in comment 16.

I filed bug 283460 for the additional cleanup work.