NetBSD Problem Report #32221

From roland@roland-illig.de  Sat Dec  3 08:29:56 2005
Return-Path: <roland@roland-illig.de>
Received: from baccf5ee.roland-illig.de (d042186.adsl.hansenet.de [80.171.42.186])
	by narn.netbsd.org (Postfix) with ESMTP id 2C55B63B883
	for <gnats-bugs@gnats.netbsd.org>; Sat,  3 Dec 2005 08:29:51 +0000 (UTC)
Message-Id: <20051203082949.D2802F5F1@baccf5ee.roland-illig.de>
Date: Sat,  3 Dec 2005 09:29:49 +0100 (CET)
From: rillig@NetBSD.org
Reply-To: rillig@NetBSD.org
To: gnats-bugs@netbsd.org
Subject: NetBSD's web documentation is not valid HTML
X-Send-Pr-Version: 3.95

>Number:         32221
>Category:       misc
>Synopsis:       NetBSD's web documentation is not valid HTML
>Confidential:   no
>Severity:       critical
>Priority:       medium
>Responsible:    www
>State:          analyzed
>Class:          sw-bug
>Submitter-Id:   net
>Arrival-Date:   Sat Dec 03 08:30:01 +0000 2005
>Closed-Date:    
>Last-Modified:  Sun Jan 20 08:28:08 +0000 2019
>Originator:     Roland Illig
>Release:        
>Organization:

>Environment:


>Description:

	The docbook templates for the NetBSD web site do not generate
	valid HTML. As "high code quality" also includes correctness of
	the resulting output a user might think the NetBSD people are
	not even able to generate valid HTML. This in turn might
	severely damage the public reputation of the NetBSD project as a
	whole.

>How-To-Repeat:

	http://validator.w3.org/check?uri=http%3A%2F%2Fwww.netbsd.org%2FDocumentation%2Fpkgsrc%2Fmakefile.html

>Fix:


>Release-Note:

>Audit-Trail:

Responsible-Changed-From-To: misc-bug-people->nonexistant-user
Responsible-Changed-By: rillig@netbsd.org
Responsible-Changed-When: Sat, 03 Dec 2005 09:16:06 +0000
Responsible-Changed-Why:
To test if I can assign PRs to arbitrary strings.


Responsible-Changed-From-To: nonexistant-user->www
Responsible-Changed-By: rillig@netbsd.org
Responsible-Changed-When: Sat, 03 Dec 2005 09:17:44 +0000
Responsible-Changed-Why:
www should be able to handle it.


Responsible-Changed-From-To: www->mishka
Responsible-Changed-By: mishka@netbsd.org
Responsible-Changed-When: Tue, 07 Mar 2006 13:15:19 +0000
Responsible-Changed-Why:
I'll take this PR, as has been recently discussed on www@.


From: "Mike M. Volokhov" <mishka@NetBSD.org>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: misc/32221
Date: Tue, 7 Mar 2006 19:38:09 +0200

 Okay, looking bit closer to our XML web-site I've found we are
 relatively near the HTML 4.01 Transitional format. Most of pages now
 can be built HTML compliant without further modifications (very often
 "bug" is an <html xmlns=""> attributes which was recently almost
 eliminated).

 But our first problem is that XML files are completely invalid
 themselves, and this may cause HTML validity breakage. In short summary:

   - intensively used custom elements without DTD/schema support;
   - using limited Simplified DocBook XML Customization DTD (man-refs problem);

 Now I'm pretty sure the following way should be used here:

   1. work close with <hrs> to achieve powerful and lightweight DTD;
   2. support authors/editors with validity tools ("make valid");
   3. work even close with <hrs> to provide correct XSLT stylesheets
      for our own tags (Website XSL looks good enough already);

 --
 Mishka.

Responsible-Changed-From-To: mishka->mishka@NetBSD.org
Responsible-Changed-By: mishka@netbsd.org
Responsible-Changed-When: Fri, 17 Mar 2006 14:04:38 +0000
Responsible-Changed-Why:
Use my email address (RT6130).


Responsible-Changed-From-To: mishka@NetBSD.org->mishka
Responsible-Changed-By: mishka@netbsd.org
Responsible-Changed-When: Fri, 17 Mar 2006 15:23:06 +0000
Responsible-Changed-Why:
GNATS dislikes email addresses so use just a name as identifier.


From: "Mike M. Volokhov" <mishka@intostroy.com>
To: gnats-bugs@netbsd.org
Cc: 
Subject: Re: misc/32221
Date: Fri, 17 Mar 2006 17:35:14 +0200

 Avoid this test message please, and sorry for the noise.

From: "Mike M. Volokhov" <mishka@netbsd.org>
To: www-changes@netbsd.org
Cc: 
Subject: Re: misc/32221 [CVS commit: htdocs/share/xsl]
Date: Tue,  7 Mar 2006 14:53:38 +0000 (UTC)

 Module Name:	htdocs
 Committed By:	mishka
 Date:		Tue Mar  7 14:53:38 UTC 2006

 Modified Files:
 	htdocs/share/xsl: global.xsl netbsd-book.xsl
 	    netbsd-docbook-html-chunk.xsl netbsd-docbook-html.xsl
 	    netbsd-html-chunk.xsl netbsd-webpage-bg.xsl netbsd-webpage-cs.xsl
 	    netbsd-webpage-de.xsl netbsd-webpage-en.xsl netbsd-webpage-es.xsl
 	    netbsd-webpage-et.xsl netbsd-webpage-fr.xsl netbsd-webpage-it.xsl
 	    netbsd-webpage-ja.xsl netbsd-webpage-ko.xsl netbsd-webpage-lt.xsl
 	    netbsd-webpage-nl.xsl netbsd-webpage-pl.xsl
 	    netbsd-webpage-pt_BR.xsl netbsd-webpage-pt_PT.xsl
 	    netbsd-webpage-ru.xsl netbsd-webpage-sv.xsl
 	    netbsd-webpage-zh_CN.xsl netbsd-webpage-zh_TW.xsl
 	    netbsd-webpage.xsl netbsd.xsl portpage.xsl webpage.xsl

 Log Message:
 Do not include HTML namespace prefixes into resulting HTML files,
 and use HTML 4.01 Transitional everywhere (we really still far from
 building XHTML). This brings us one step closer to HTML valid output.


 To generate a diff of this commit:
 cvs rdiff -r1.7 -r1.8 htdocs/share/xsl/global.xsl
 cvs rdiff -r1.2 -r1.3 htdocs/share/xsl/netbsd-book.xsl \
     htdocs/share/xsl/netbsd-webpage-cs.xsl \
     htdocs/share/xsl/netbsd-webpage-pt_PT.xsl \
     htdocs/share/xsl/netbsd-webpage-sv.xsl \
     htdocs/share/xsl/netbsd-webpage.xsl
 cvs rdiff -r1.10 -r1.11 htdocs/share/xsl/netbsd-docbook-html-chunk.xsl \
     htdocs/share/xsl/netbsd-docbook-html.xsl
 cvs rdiff -r1.3 -r1.4 htdocs/share/xsl/netbsd-html-chunk.xsl \
     htdocs/share/xsl/netbsd-webpage-en.xsl \
     htdocs/share/xsl/netbsd-webpage-es.xsl \
     htdocs/share/xsl/netbsd-webpage-ru.xsl
 cvs rdiff -r1.1 -r1.2 htdocs/share/xsl/netbsd-webpage-bg.xsl \
     htdocs/share/xsl/netbsd-webpage-et.xsl \
     htdocs/share/xsl/netbsd-webpage-fr.xsl \
     htdocs/share/xsl/netbsd-webpage-it.xsl \
     htdocs/share/xsl/netbsd-webpage-ja.xsl \
     htdocs/share/xsl/netbsd-webpage-pl.xsl \
     htdocs/share/xsl/netbsd-webpage-pt_BR.xsl \
     htdocs/share/xsl/netbsd-webpage-zh_CN.xsl \
     htdocs/share/xsl/netbsd-webpage-zh_TW.xsl
 cvs rdiff -r1.4 -r1.5 htdocs/share/xsl/netbsd-webpage-de.xsl \
     htdocs/share/xsl/netbsd-webpage-ko.xsl
 cvs rdiff -r1.5 -r1.6 htdocs/share/xsl/netbsd-webpage-lt.xsl \
     htdocs/share/xsl/netbsd-webpage-nl.xsl
 cvs rdiff -r1.9 -r1.10 htdocs/share/xsl/netbsd.xsl
 cvs rdiff -r1.14 -r1.15 htdocs/share/xsl/portpage.xsl
 cvs rdiff -r1.27 -r1.28 htdocs/share/xsl/webpage.xsl

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

From: "Mike M. Volokhov" <mishka@netbsd.org>
To: www-changes@netbsd.org
Cc: 
Subject: Re: misc/32221 [CVS commit: htdocs]
Date: Wed, 22 Mar 2006 08:18:42 +0000 (UTC)

 Module Name:	htdocs
 Committed By:	mishka
 Date:		Wed Mar 22 08:18:42 UTC 2006

 Modified Files:
 	htdocs/guide/en/share: default-html.xsl
 	htdocs/guide/es/share: default-html.xsl
 	htdocs/guide/ko/share: default-html.xsl
 	htdocs/guide/nl/share: default-html.xsl
 	htdocs/guide/pl/share: default-html.xsl
 	htdocs/share/xsl: netbsd-docbook-html-chunk.xsl

 Log Message:
 misc/32221: Set correct DOCTYPE definitions on both single and
 chunked HTML output of the NetBSD Guide.


 To generate a diff of this commit:
 cvs rdiff -r1.4 -r1.5 htdocs/guide/en/share/default-html.xsl
 cvs rdiff -r1.2 -r1.3 htdocs/guide/es/share/default-html.xsl
 cvs rdiff -r1.3 -r1.4 htdocs/guide/ko/share/default-html.xsl
 cvs rdiff -r1.4 -r1.5 htdocs/guide/nl/share/default-html.xsl
 cvs rdiff -r1.4 -r1.5 htdocs/guide/pl/share/default-html.xsl
 cvs rdiff -r1.11 -r1.12 htdocs/share/xsl/netbsd-docbook-html-chunk.xsl

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

State-Changed-From-To: open->analyzed
State-Changed-By: mishka@netbsd.org
State-Changed-When: Wed, 22 Mar 2006 15:47:21 +0000
State-Changed-Why:
Working on this PR I found that DocBook and Website XSLT are very
likely produce valid HTML output. Analysing our HTML files I have found
that most pages are invalid because of following reasons:

1) "Stray" XML namespace declarations. Please note that that
   declarations are incorrectly influenced on some other tag
   construction, such as <br></br> (must be just <br>).
2) Absent DOCTYPE declarations.
3) Possible incorrect HTML schema.
4) Possible some other reasons.
5) CSS validity.

I hope I've fixed (1) and (2), and now most of XML files can be used as
source for valid HTML pages. For example, the NetBSD Guide is now valid
HTML 4.01 Transitional document.

Regarding (3) and (4) IMHO we should:

1) have a way to detect/verify validation for all HTML pages (some sort
   of "make htmllint"). Validator engine used by w3.org is available
   for downloads from their site, and I'm wondering is it packaged with
   pkgsrc, so we can include it into our toolchain.
2) because valid XML DocBook/Website documents would result in valid
   HTML, we should have a way to validate our XML pages (i.e. just as
   with HTML sort of "make xmllint"). Currently you may try validate
   your own XML files as follows:
   a) set {XML,SGML}_CATALOG_FILES to "$HTDOCS/share/xml/catalog-common.xml
      $HTDOCS/share/xml/catalog.xml $LOCALBASE/share/xml/catalog" (space
      separated list).
   b) use xmllint(1) by the following way:
      xmllint --noout --nonet --xinclude --catalogs --valid FILE_NAME

The second part is really broken because we're using Simplified Docbook
as backend for Website. It doesn't have <sect[1-6]> and many other
widely used things (don't know exactly, but I'm sure :-). Because all
this will enweight our toolchain and bind use even more to XML/Docbook,
we must talk with <hrs> about our website again.

The (5) can be very easy eliminated completely. All problems are shown here:

 http://jigsaw.w3.org/css-validator/validator?uri=http%3A%2F%2Fwww.netbsd.org%2FNetBSD.css&usermedium=all

Responsibles for this errors are <grant> and <keihan>.



From: "Mike M. Volokhov" <mishka@netbsd.org>
To: gnats-bugs@netbsd.org
Cc: 
Subject: Re: misc/32221
Date: Wed, 29 Aug 2007 14:53:20 +0000

 The primary CSS for www.NetBSD.org has been changed to
 http://www.NetBSD.org/global.css and it is now valid.

From: David Holland <dholland-bugs@netbsd.org>
To: gnats-bugs@netbsd.org, www@netbsd.org
Cc: 
Subject: Re: misc/32221: NetBSD's web documentation is not valid HTML
Date: Sun, 15 Feb 2009 03:17:20 +0000

 Is this fully fixed? The PR has been sitting around for nearly 18
 months since it was at least partly fixed. If it's fixed, please close
 it... if not, well, *poke* :-)

 -- 
 David A. Holland
 dholland@netbsd.org

Responsible-Changed-From-To: mishka->www
Responsible-Changed-By: dholland@NetBSD.org
Responsible-Changed-When: Sun, 20 Jan 2019 08:28:08 +0000
Responsible-Changed-Why:
Reset responsible field for retired developer.


>Unformatted:

NetBSD Home
NetBSD PR Database Search

(Contact us) $NetBSD: query-full-pr,v 1.39 2013/11/01 18:47:49 spz Exp $
$NetBSD: gnats_config.sh,v 1.9 2014/08/02 14:16:04 spz Exp $
Copyright © 1994-2007 The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.