Re: HTML docs

[Phil Edwards <phil at jaj dot com>]

On Thu, Aug 22, 2002 at 05:22:19PM +0100, Jonathan Wakely wrote:
> On Wed, Aug 21, 2002 at 08:22:11PM +0100, Joseph S. Myers wrote:
> 
> > I'm not an XHTML expert, but if you want those libstdc++ pages that are in
> > the source tree to be preprocessed (which would require them to be in
> > XHTML) then Phil's the maintainer of the update_web_docs_libstdcxx script
> > that handles making those docs available online.
> 
> Well, back to the libstdc++ list then   :-)

I'm cc'ing Gerald as the author of the preprocessing script... something
doesn't look right to me.

The update_web_docs (non-libstdc++ version) seems to do this:

    - run makeinfo for onlinedocs area
    - make gzipped copies of all html files (for smart browsers)
    - run makeinfo on just the install docs
    - run the preprocessor on everything

The third line is via gcc/doc/install.texi2html.

I don't understand where/when/what the preprocessor does.  I picked a
random html file under onlinedocs/gcc and it wasn't preprocessed, so I'm
not sure what to do.


> I can submit a patch to convert the entire docs/html tree to valid XHTML
> in the next couple of days - if you want them brought inline. It's a
> simple process with a bit of scripting, but if there's no interest, I
> won't bother.
> 
> Assuming for now the patch is wanted...

Let's do it.

> I've already done a few pages, these can be seen at
> http://www.compsoc.man.ac.uk/~cow/tmp/gcc/
> (try pages in /, /ext/ and /faq/, broken links means I've not done that page)

Excellent!

> I've kept the appearance the same, just reordered a few tags and added end
> tags where they're required in XHTML, except for ext/sgiexts.html, where I
> added <code> tags around some identifiers which weren't marked up. Can I
> do that for all the names in that file that should be <code> ?
> For instance, "operator()" is sometimes written "op()", can I change that
> to "<code>operator()</code>" ?

I've no objection.

> (basically, the pages look like they were
> written as notes that have been promoted to docs,

That's exactly what happened.


> The pages at the above URL have the standard GCC header and footers, as
> they'd be when preprocessed, but the copies in my cvs don't, in line with
> http://gcc.gnu.org/contribute.html - I'm processing them myself as I copy
> them to that web page.

Yeah, I'd leave out the massive boilerplate footers 'n' stuff.  If we're
going to add that at all, it should be only on the webserver, via the
preprocessor.


> I've noticed that ext/lwg-active.html and lwg-defects.html contain broken
> links to the non-existent files lwg-index.html, lwg-status.html and
> lwg-toc.html. Are these files supposed to be in libstdc++, or is it a
> consequence of copying lwg-active and lwg-defects straight from the LWG
> site at http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/ ?
> If the pages are copied straight from the LWG pages, should I leave them
> alone? Otherwise the XHTML versions will be overwritten every time Matt
> Austern updates the lists.

They are copied from LWG and should be left alone.  Somewhere there's a
file named (I think) codingconventions.html that mentions weird files,
including these two.


> -- 
> "There are only two industries that refer to their customers as 'users'."
> 	- Edward Tufte 

Gonna have to remember that sig.  :-)


Thanks very much!

Phil

-- 
I would therefore like to posit that computing's central challenge, viz. "How
not to make a mess of it," has /not/ been met.
                                                 - Edsger Dijkstra, 1930-2002