272147 - Make the NSPR Reference validate

Status: RESOLVED WONTFIX

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

Description

[Anne (:annevk)]

These documents use very out of date and incorrect markup. Elements like
MAINCONTENT et cetera.

fantasai, could you review the patches?

Comment 1

[Anne (:annevk)]

Attachment: printro.html

Here is the first document. Before I continue I want some feedback. Processing
such documents takes time so I want to know if I'm heading the right direction
and if I should change something in the way I'm processing them.

Comment 2

[dolphinling]

I'm going to help out on this, though anne said I should wait to start until
fantasai comments on the first patch. 

For now, two comments of my own:

1. The w3c validator complains of an id starting with 1 on line 13, a tag
missing "> on line 31, and some badly nested stuff on line 309.

2. Do we want to put links (rel=start, next, prev, contents, others?) in the head?

Comment 3

[fantasai]

I sure hope you're using either regex or tidy on these things Anne. :)

> In general, a monitor is

monitor should be <dfn> here, I think.

You need to use class="toc" for the tocs, and class="code" for the code blocks.
Use <div class="section"> to delimit sections.
Other than that the code looks good.

If your editor has a reformat command that can make the lines break a little
more evenly (I think emacs has such a command), that would be nice. If not, it's ok.

I agree with dolphinling's comments; please, do put next/prev/toc links in the
head. :)

There's an excessive amount of numeric IDing. Do you think it would make sense
to scrap them all in favor of readable names just on all the section headers?
(Your call.)

For the title, I'd move "Chapter 1" to the end and put it in parentheses:
  NSPR Reference: Introduction to NSPR (Chapter 1)

Comment 4

[dolphinling]

Attachment: prerr.html (Chapter 34)

As this is my first major re-markuping of a page here, it probably needs more
review than most. Have fun :-)

Comment 5

[fantasai]

Review comments:

 - Please indent your code. Every <div> should go in two spaces. It makes it
   much easier to see the structure of the document from the code, and it also
   makes it much less likely that one will forget a closing tag. See the source
   code for the markup guide or the website cvs doc for an example.
   Many editors have an indenting function; check your menus. (You might need to
   set the indentation to two spaces somewhere in the prefs, though.) If yours
   doesn't, you may still be able to use search/replace on the beginning of a
   line to do indentation. 

   Just a note for you guys, might be helpful:
   I know that jedit can do both indentation and rewrapping that preserves
   indentation. I remember using it to fix up a document awhile back.

 - Unless they are code names (like PR_Bool), anchor names should follow the
   same guidelines set out for filenames:
     http://www.mozilla.org/contribute/writing/guidelines#filenames
   In particular: all lower case, and use hypens, not underscores.

 - The table of macro definitions should be a <dl>.

 - You're missing class="toc" on the Error Codes navigation list.

Comment 6

[dolphinling]

Attachment: prerr.html (Chapter 34) -- version 2

Comments addressed. :-)

Comment 7

[fantasai]

I would put in a bit more whitespace -- newlines between paragraphs and sections
and the like. However, that's really up to you. What I would like is for you to
put in all the closing paragraph tags </p>. With that change, r+ fantasai

Comment 8

[dolphinling]

Attachment: prerr.html (Chapter 34) -- version 3

Paragraph tags closed. I left the whitespace as it was, since I couldn't really
find any consistent way to insert line breaks, and it looked bad when it was
inconsistent.

Comment 9

[dolphinling]

Attachment: plhash.html (Chapter 33)

A few comments in the file, mostly things that looked like they should be in
<code> tags but weren't in the original.

Comment 10

[fantasai]

 Yes, NSPR should probably be marked up as <abbr>

> portable library -- data structures

replace -- with &#8212; (emdash)

> should the h be inside the code?

yes

> <strong>Warning: </strong>The 

<strong>Warning:</strong> The

> hash-table-types-and-constants

This is redundant; the whole document is about hash tables.
Just call it 'types'

> hash-table-functions

just 'functions'

I agree with your comments about <code>.

Comment 11

[dolphinling]

Attachment: prrng.html (Chapter 32)

This was a nice short one :-)

On my last patch you didn't answer the question about whether line 49 should be
a ul or not.

Comment 12

[fantasai]

wtchang - biesi said you should be CCed on this bug

Comment 13

[dolphinling]

Attachment: prerr.html (Chapter 34) -- version 3.1

Because some of these documents have subheadings in places and others don't,
(compare the outline of chapter 3 to chapter 4) fantasai said we should skip a
heading level on the ones that don't.

Comment 14

[dolphinling]

Attachment: prerr.html (Chapter 34) -- version 3.1

Oops, attached the wrong file before.

Comment 15

[dolphinling]

Attachment: plhash.html (Chapter 33) -- version 2

Comments addressed, and headings redone.

Comment 16

[dolphinling]

Attachment: prrng.html (Chapter 32) -- version 1.1

headings redone

Comment 17

[Anne (:annevk)]

You don't have to update your documents again, but link to 'index.html' as './'.
We also want |lang="en"| on the HTML element. Just add those when you check the
document in.

Comment 18

[Anne (:annevk)]

Attachment: Prtyp.html (Capter 2)

This was quite a lot of work. Ever seen a real world H6?

Comment 19

[dolphinling]

Attachment: prtpool.html (Chapter 31)

It's been a couple months since I last did one of these, so you might want to
check this one a little more than normal...

Comment 20

[dolphinling]

Attachment: prtpool.html (Chapter 31) -- version 1.1

Oops, I had some dd/dts mixed up.

Comment 21

[dolphinling]

Attachment: pripcsem.html (Chapter 30)

Comment 22

[fantasai]

Looks pretty good to me. :)

Comment 23

[Reed Loden [:reed]]

It seems not all the patches in this bug were committed. Should I commit them (making sure that nothing gets overwritten in the process)?

Comment #22 seems to give the go-ahead on doing so.

Comment 24

[fantasai]

yes, go ahead

Comment 25

[Reed Loden [:reed]]

Assigning to myself to put it on my TODO list.

Comment 26

[Reed Loden [:reed]]

Checking in Prtyp.html;
/cvsroot/mozilla-org/html/projects/nspr/reference/html/Prtyp.html,v  <--  Prtyp.html
new revision: 1.6; previous revision: 1.5
done
Checking in plhash.html;
/cvsroot/mozilla-org/html/projects/nspr/reference/html/plhash.html,v  <--  plhash.html
new revision: 1.5; previous revision: 1.4
done
Checking in prerr.html;
/cvsroot/mozilla-org/html/projects/nspr/reference/html/prerr.html,v  <--  prerr.html
new revision: 1.5; previous revision: 1.4
done
Checking in pripcsem.html;
/cvsroot/mozilla-org/html/projects/nspr/reference/html/pripcsem.html,v  <--  pripcsem.html
new revision: 1.4; previous revision: 1.3
done
Checking in prrng.html;
/cvsroot/mozilla-org/html/projects/nspr/reference/html/prrng.html,v  <--  prrng.html
new revision: 1.4; previous revision: 1.3
done
Checking in prtpool.html;
/cvsroot/mozilla-org/html/projects/nspr/reference/html/prtpool.html,v  <--  prtpool.html
new revision: 1.4; previous revision: 1.3
done

Comment 27

[dolphinling]

Just noticed that prtpool.html has a <div class="section" with no > at the end, on line 497. Apparently that's valid (??) but it's not intended.

Comment 28

[Reed Loden [:reed]]

(In reply to comment #27)
> Just noticed that prtpool.html has a <div class="section" with no > at the end,
> on line 497. Apparently that's valid (??) but it's not intended.
> 

Checking in mozilla-org/html/projects/nspr/reference/html/prtpool.html;
/cvsroot/mozilla-org/html/projects/nspr/reference/html/prtpool.html,v  <--  prtpool.html
new revision: 1.5; previous revision: 1.4
done

Comment 29

[Reed Loden [:reed]]

Comment on attachment 167467 [details]
printro.html

This file still needs to be corrected as per the comments in the first of the bug.

Comment 30

[Justin Wood (:Callek)]

Just a note, the entire NSPR API Reference has begun being migrated to devmo (MDC), so this bug may be reso/invalid soon.

(once a redirect is set up)

MDC Url: http://developer.mozilla.org/en/docs/NSPR_API_Reference

I only even noticed this bug when formatting was different on a page I am already started migrating.

Comment 31

[Reed Loden [:reed]]

(In reply to comment #30)
> Just a note, the entire NSPR API Reference has begun being migrated to devmo
> (MDC), so this bug may be reso/invalid soon.
> 
> (once a redirect is set up)
> 
> MDC Url: http://developer.mozilla.org/en/docs/NSPR_API_Reference

How much is left to go?

Comment 32

[Justin Wood (:Callek)]

Aprox three quarters left to be migrated, if you want to help migrate, feel free. (Follow current conventions where possible).

One issue 'we' still need to figure out in the migration to MDC is the issue outlined on: http://developer.mozilla.org/en/docs/Talk:PR_SetConcurrency

but this is all a bit out of scope for this bug.

Comment 33

[Gérard Talbot]

Hello all,

I have read comments made so far.

I can use latest available HTML Tidy (22 March 2008), just like I have done in other bugs (eg bug 389104). I can use class="toc" for the tocs, class="code" for the code blocks, <div class="section"> to delimit sections, I can link to 'index.html' as './' and put lang="en" on the HTML element. Etc.

Webpages needing to be upgraded accordingly
===========================================

http://www.mozilla.org/projects/nspr/reference/html/ 1609 validation markup errors 

Chapter 1:
http://www.mozilla.org/projects/nspr/reference/html/printro.html 45 validation markup errors (with strict DTD)

Chapter 3:
http://www.mozilla.org/projects/nspr/reference/html/prthrd.html 69 validation markup errors

Chapter 4:
http://www.mozilla.org/projects/nspr/reference/html/prinit.html 41 validation markup errors (with strict DTD)

Chapter 5:
http://www.mozilla.org/projects/nspr/reference/html/prlock.html 38 validation markup errors

Chapter 6:
http://www.mozilla.org/projects/nspr/reference/html/prcvar.html 39 validation markup errors

Chapter 7:
http://www.mozilla.org/projects/nspr/reference/html/prmon.html 50 validation markup errors

Chapter 8:
http://www.mozilla.org/projects/nspr/reference/html/prcmon.html 48 validation markup errors

Chapter 9:
http://www.mozilla.org/projects/nspr/reference/html/priotyp.html 31 validation markup errors

ETC.

I can take this bug but I can not and will not migrate the webpages though.
I wish someone would confirm that those documents' markup code still need to be upgraded.
From what I've seen, only chapter 2 and chapters 30 to 34 have been upgraded. Am I missing something?

Comment 34

[dolphinling]

Gérard,

At this point there's really no desire to fix the pages on www.m.o at all. MDC is where they belong, and once everything is there, the originals will probably be removed. Given that, there's really no point to fixing the originals; migration is all that's needed.

Thanks though!

Comment 35

[Gérard Talbot]

Thank you for your quick reply, dolphinling!

> there's really no point to fixing the originals;
> migration is all that's needed.

Then it should be ok to resummarize from 
"Make the NSPR Reference validate"
to
"Migrate the NSPR Reference to MDC" , ok? 
Just asking..

I will also remove the blocking of bug 151557 ... if no one objects. Thanks!

Comment 36

[Wan-Teh Chang]

Please do not resummarize this bug, which has 30
30 comments on the original description.  It'd
be confusing.  We should open a new bug if we need
a bug for the migration to MDC.  You can use the
status whiteboard to describe what's left to do.

I think this bug can be resolved WONTFIX now.

Comment 37

[Gérard Talbot]

I've added a note to the whiteboard.

I've removed blocking bug 151557.

Comment 38

[Gordon P. Hemsley [:GPHemsley]]

I filed bug 670591 for the migration to MDN.

Resolving this WONTFIX.