Debian Bug report logs - #613946
Debian policy should use DocBook XML for source

version graph

Package: debian-policy; Maintainer for debian-policy is Debian Policy List <debian-policy@lists.debian.org>; Source for debian-policy is src:debian-policy.

Reported by: Christoph Weber <c.weber@ideo-labs.com>

Date: Fri, 18 Feb 2011 12:36:02 UTC

Severity: wishlist

Tags: patch

Merged with 175064

Found in versions debian-policy/3.8.0.1, debian-policy/3.9.1.0

Blocking fix for 661417: Policy document cleanups

Reply or subscribe to this bug.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#613946; Package debian-policy. (Fri, 18 Feb 2011 12:36:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Christoph Weber <c.weber@ideo-labs.com>:
New Bug report received and forwarded. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 18 Feb 2011 12:36:05 GMT) Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Christoph Weber <c.weber@ideo-labs.com>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: debian-policy: anchor issues in HTML version
Date: Fri, 18 Feb 2011 13:27:39 +0100
Package: debian-policy
Version: 3.8.0.1
Severity: minor

When you view the HTML version of the Debian Policy with a browser
like Lynx or SeaMonkey/IceApe (which interpret <link> elements in
the header), you'll notice some unfiltered tags like:

| 4.4 Debian changelog: <code>debian/changelog</code>
or
| 7.2 Binary Dependencies - <samp>Depends</samp>

Apparently, <code> and <samp> etc. should be filtered out in the title
text of the link elements.


Another tight related issue are the anchors that serve as destination
for those link elements.  Currently, they are declared like this:

| <h2><a name="s-binarydeps"></a>7.2 Binary Dependencies -
| <samp>Depends</samp>, <samp>Recommends</samp>, <samp>Suggests</samp>,
| <samp>Enhances</samp>, <samp>Pre-Depends</samp></h2>

There is no link text.  A better solution would be:

| <h2><a name="s-binarydeps">7.2 Binary Dependencies -
| <samp>Depends</samp>, <samp>Recommends</samp>, <samp>Suggests</samp>,
| <samp>Enhances</samp>, <samp>Pre-Depends</samp></a></h2>

This will meet the recommendations of the WCAG for links.
(<http://www.w3.org/TR/2008/REC-WCAG20-20081211/#navigation-mechanisms>)

Main purpose: I like to use CSS to highlight anchor targets.
This is useful when you want to link to some sub-heading in
your documentation et al.  It looks like this:

| h1[id]:hover:after,
| h2[id]:hover:after,
| h3[id]:hover:after,
| h4[id]:hover:after {
|     content:" #"attr(id);
|     font-size: smaller;
| }
| a[name]:hover:after {
|     content:" #"attr(name);
|     font-size: smaller;
| }

When you hover over an heading h1 .. h4 or anchor, the browser will
show the id or name at the end of the line.  Empty anchors sabotage
this, as they take no space and cannot be hovered.  Changing the
anchors or switching to headings with ids should fix that problem,
too.

Regards,
Christoph

P.S.: Version 3.9.1.0 seems to have the same issues.

-- System Information:
Debian Release: 5.0.8
  APT prefers oldstable
  APT policy: (500, 'oldstable')
Architecture: i386 (i686)

Kernel: Linux 2.6.26-2-686 (SMP w/2 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=de_DE.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

debian-policy depends on no packages.

debian-policy recommends no packages.

Versions of packages debian-policy suggests:
pn  doc-base                      <none>     (no description available)

-- no debconf information




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#613946; Package debian-policy. (Fri, 18 Feb 2011 17:54:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 18 Feb 2011 17:54:05 GMT) Full text and rfc822 format available.

Message #10 received at 613946@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Christoph Weber <c.weber@ideo-labs.com>
Cc: 613946@bugs.debian.org
Subject: Re: Bug#613946: debian-policy: anchor issues in HTML version
Date: Fri, 18 Feb 2011 09:51:28 -0800
Christoph Weber <c.weber@ideo-labs.com> writes:

> When you view the HTML version of the Debian Policy with a browser like
> Lynx or SeaMonkey/IceApe (which interpret <link> elements in the
> header), you'll notice some unfiltered tags like:

[...]

The HTML is generated by DebianDoc-SGML, so none of this can be fixed
until we convert Policy to a different documentation system.  The HTML
output is from another tool and basically is what it is.

Doing that conversion is something that we want to do, but no one working
on Policy has had much free time lately.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#613946; Package debian-policy. (Wed, 02 Mar 2011 04:30:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 02 Mar 2011 04:30:03 GMT) Full text and rfc822 format available.

Message #15 received at 613946@bugs.debian.org (full text, mbox):

From: Jonathan Nieder <jrnieder@gmail.com>
To: debiandoc-sgml@packages.debian.org
Cc: Christoph Weber <c.weber@ideo-labs.com>, 613946@bugs.debian.org
Subject: Re: debian-policy: anchor issues in HTML version
Date: Tue, 1 Mar 2011 22:24:05 -0600
user debian-policy@packages.debian.org
clone 613946 -1 -2
retitle -1 debiandoc2html: <link> titles should not have embedded tags
retitle -2 debiandoc2html: <a name> anchors should enclose heading text
severity -1 normal
severity -2 minor
reassign -1 debiandoc-sgml 1.2.20
reassign -2 debiandoc-sgml 1.2.20
usertags 613946 + packaging
quit

Hi Osamu,

Christoph Weber noticed:

> When you view the HTML version of the Debian Policy with a browser
> like Lynx or SeaMonkey/IceApe (which interpret <link> elements in
> the header), you'll notice some unfiltered tags like:
>
> | 4.4 Debian changelog: <code>debian/changelog</code>
> or
> | 7.2 Binary Dependencies - <samp>Depends</samp>
>
> Apparently, <code> and <samp> etc. should be filtered out in the title
> text of the link elements.
>
> Another tight related issue are the anchors that serve as destination
> for those link elements.  Currently, they are declared like this:
>
> | <h2><a name="s-binarydeps"></a>7.2 Binary Dependencies -
> | <samp>Depends</samp>, <samp>Recommends</samp>, <samp>Suggests</samp>,
> | <samp>Enhances</samp>, <samp>Pre-Depends</samp></h2>
>
> There is no link text.  A better solution would be:
>
> | <h2><a name="s-binarydeps">7.2 Binary Dependencies -
> | <samp>Depends</samp>, <samp>Recommends</samp>, <samp>Suggests</samp>,
> | <samp>Enhances</samp>, <samp>Pre-Depends</samp></a></h2>

See http://bugs.debian.org/613946 for more details.  Thoughts?

The following testcase[1] reproduces the problem.

Thanks,
Jonathan

[1] Usage: "debiandoc2html testcase.sgml".

<!doctype debiandoc system>
<debiandoc>
  <book>
    <titlepag>
      <title>Example</title>
      <author>Authors</author>
    </titlepag>
    <toc detail="chapt">
    <chapt id="scope">
      <heading>About this manual</heading>
    </chapt>
    <chapt id="dpkgchangelog">
      <heading>Debian changelog: <file>debian/changelog</file></heading>
    </chapt>
  </book>
</debiandoc>




Bug 613946 cloned as bugs 616042, 616043. Request was from Jonathan Nieder <jrnieder@gmail.com> to control@bugs.debian.org. (Wed, 02 Mar 2011 04:30:03 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#613946; Package debian-policy. (Fri, 04 Mar 2011 14:15:12 GMT) Full text and rfc822 format available.

Acknowledgement sent to Osamu Aoki <osamu@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 04 Mar 2011 14:15:12 GMT) Full text and rfc822 format available.

Message #22 received at 613946@bugs.debian.org (full text, mbox):

From: Osamu Aoki <osamu@debian.org>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: debiandoc-sgml@packages.debian.org, Christoph Weber <c.weber@ideo-labs.com>, 613946@bugs.debian.org, 616042-done@bugs.debian.org, 616043@bugs.debian.org
Subject: Re: debian-policy: anchor issues in HTML version
Date: Fri, 4 Mar 2011 23:13:54 +0900
severity 616043 wishlist
tags 616043 wontfix
severity 613946 wishlist
thanks

Hi,

Before I start, let me remind people that it is more important to
convert all these SGML documents to DocBook XML.  So far, I am having
good success for maint-guide.  I will work on this document once I get
comfortable doing this conversion.

 http://wiki.debian.org/DocbookXmlTransition

But policy is such a high profile document, I will work on this later.

On Tue, Mar 01, 2011 at 10:24:05PM -0600, Jonathan Nieder wrote:
> user debian-policy@packages.debian.org
> clone 613946 -1 -2
> retitle -1 debiandoc2html: <link> titles should not have embedded tags

What debiandoc2html should do as default is pure taste issue.
I know there have been many flip-flopping.  Its enough.
The user of debiandoc2html can disable this by using -L option.

So this is not bug for debiandoc-sgml.

Please see http://bugs.debian.org/402122 first and read on to:

 http://bugs.debian.org/402122 (current default rationale)
 http://bugs.debian.org/140677 (old history)

On this basis, I am closing this bug #616042 for debiandoc-sgml.

If bug reporter carefully read all these bug reports, this aspect of bug
#613946 is at best wishlist and debian-policy maintainer should assign
wontfix tag unless submitter gives good rationale.  I think we provide
document for most browsers with decent capability.  We do not cut down
good feature useful for most user just for lowest denominator
application.  There are some console browsers such as w3m which can
handle this OK.

> retitle -2 debiandoc2html: <a name> anchors should enclose heading text

Hmmm... this aspect of this bug has been so for long time.  I was
wondering on this when I took over this package.  I do not see any real
negative so this is purely aesthetic concern.  If you can cite some RFC
etc., then this is real minor bug otherwise this is wishlist bug which I
will mark as wontfix since I am not going to change this old program's
behavior any more unless it is gross problem.  Until I get clear
argument, I am marking this as wishlist/wontfix so I will not get
similar complain.

> severity -1 normal
> severity -2 minor
> reassign -1 debiandoc-sgml 1.2.20
> reassign -2 debiandoc-sgml 1.2.20
> usertags 613946 + packaging

I see you are doing BTS cleaning.  

> See http://bugs.debian.org/613946 for more details.  Thoughts?

It has been answered.

This should be fixed on Lynx side.  They show up since this does not
understand as I think. But I have not fully investigated so not ready to
reassign this to them.

Properly displaying provided feature-rich HTML is burden of clients.  I
think we should not blame generating software and created data.  That is
my thought.

Thus I think this is not really a bug of debian-policy.  At best it is
wishlist bug.  Sevrity changed to wishlist.

If bug triage people think this is not a bug of debian-policy, please
feel free to close this bug.

I should say the more useful wishlist bug is "debian-policy should use
DocBook XML for source" :-)

Osamu




Severity set to 'wishlist' from 'minor' Request was from Osamu Aoki <osamu@debian.org> to control@bugs.debian.org. (Fri, 04 Mar 2011 14:15:17 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#613946; Package debian-policy. (Fri, 04 Mar 2011 22:21:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 04 Mar 2011 22:21:03 GMT) Full text and rfc822 format available.

Message #29 received at 613946@bugs.debian.org (full text, mbox):

From: Jonathan Nieder <jrnieder@gmail.com>
To: 616042@bugs.debian.org
Cc: Christoph Weber <c.weber@ideo-labs.com>, 613946@bugs.debian.org, 616043@bugs.debian.org
Subject: Re: debian-policy: anchor issues in HTML version
Date: Fri, 4 Mar 2011 16:18:28 -0600
reopen 616042
retitle 616042 debiandoc2html: title attribute of <link> tags must be plain text
severity 616042 wishlist
tags 616042 + wontfix
retitle 613946 Debian policy should use DocBook XML for source
quit

Hi Osamu,

Osamu Aoki wrote:

>  http://wiki.debian.org/DocbookXmlTransition

Thanks, I didn't know about that page.  I agree that it's not worth
spending time on other aspects.  So please feel free to ignore the
rest of this message. ;-)

> On Tue, Mar 01, 2011 at 10:24:05PM -0600, Jonathan Nieder wrote:

>> retitle -1 debiandoc2html: <link> titles should not have embedded tags
>
> What debiandoc2html should do as default is pure taste issue.
> I know there have been many flip-flopping.  Its enough.
> The user of debiandoc2html can disable this by using -L option.

I think you might have misunderstood the bug.  I am very happy that
the <link> tags are included; the only problem is that the "title"
attribute contains embedded tags.  As the HTML standard explains:

	The title attribute gives the title of the link. With one
	exception, it is purely advisory. The value is text.

All user agents I know that display the "title" attribute do display
it as plain text.

That said, I would agree with calling it wishlist/wontfix.  I'm
reopening the bug for documentation, so people looking at the BTS can
find another reason to switch to docbook.

> There are some console browsers such as w3m which can
> handle this OK.

That sounds like a bug in w3m, then.  Though I do not actually see the
<link> tags when I open policy in w3m --- are you sure w3m even tries
to handle this?

> If you can cite some RFC
> etc., then this is real minor bug otherwise this is wishlist bug which I
> will mark as wontfix since I am not going to change this old program's
> behavior any more unless it is gross problem.  Until I get clear
> argument, I am marking this as wishlist/wontfix so I will not get
> similar complain.

All the examples of anchor targets (<a name="foo">) in the HTML
standard use it to enclose some descriptive text or similar content.
Christoph's example of using a stylesheet to highlight link targets
certainly puts it in the realm of what the WCAG are supposed to
describe.  But I admit, I cannot find any document that comes out and
says so.

> I should say the more useful wishlist bug is "debian-policy should use
> DocBook XML for source" :-)

*nod*  Now that the debiandoc side has been nicely filed away, I'm
retitling the bug.  Hint to anyone working on this: the debconf spec
is already DocBook XML, so you can steal its rules.

Thanks for a thorough response.

Jonathan




Changed Bug title to 'Debian policy should use DocBook XML for source' from 'debian-policy: anchor issues in HTML version' Request was from Jonathan Nieder <jrnieder@gmail.com> to control@bugs.debian.org. (Fri, 04 Mar 2011 22:21:11 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#613946; Package debian-policy. (Sat, 16 Apr 2011 19:09:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Osamu Aoki <osamu@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 16 Apr 2011 19:09:04 GMT) Full text and rfc822 format available.

Message #36 received at 613946@bugs.debian.org (full text, mbox):

From: Osamu Aoki <osamu@debian.org>
To: Debian Bug Tracking System <613946@bugs.debian.org>
Subject: debian-policy: converted to menu-policy.dbk
Date: Sun, 17 Apr 2011 03:59:57 +0900
[Message part 1 (text/plain, inline)]
Package: debian-policy
Version: 3.9.1.0
Severity: normal

Hi,

Here is docbook XML converted file as attached.

If I get git write access, I can start converting the whole package as I
just did for maint-guide in git branch :-)

Try 
$ make version
$ dblatex menu-policy.dbk

You get nice PDF.  For actual packaging, we may do a bit more touch ups
like I did for maint-guide. (in DDP SVN)

Osamu

-- System Information:
Debian Release: 6.0.1
  APT prefers stable-updates
  APT policy: (500, 'stable-updates'), (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 2.6.32-5-amd64 (SMP w/2 CPU cores)
Locale: LANG=en_US.utf8, LC_CTYPE=en_US.utf8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

debian-policy depends on no packages.

debian-policy recommends no packages.

Versions of packages debian-policy suggests:
ii  doc-base                      0.9.5      utilities to manage online documen

-- no debconf information
[menu-policy.dbk (text/plain, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#613946; Package debian-policy. (Sat, 16 Apr 2011 19:21:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Osamu Aoki <osamu@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 16 Apr 2011 19:21:03 GMT) Full text and rfc822 format available.

Message #41 received at 613946@bugs.debian.org (full text, mbox):

From: Osamu Aoki <osamu@debian.org>
To: 613946@bugs.debian.org
Subject: debian-mime --> DocBook XML
Date: Sun, 17 Apr 2011 04:16:52 +0900
[Message part 1 (text/plain, inline)]
Hi,

Here is DocBook converted one from mime-policy.sgml.

I wonder why this is searate document from policy.  (Too small)

Osamu
[mime-policy.dbk (text/plain, attachment)]

Forcibly Merged 175064 613946. Request was from Osamu Aoki <osamu@debian.org> to control@bugs.debian.org. (Sat, 16 Apr 2011 19:21:04 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#613946; Package debian-policy. (Sat, 16 Apr 2011 19:30:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Osamu Aoki <osamu@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 16 Apr 2011 19:30:03 GMT) Full text and rfc822 format available.

Message #48 received at 613946@bugs.debian.org (full text, mbox):

From: Osamu Aoki <osamu@debian.org>
To: 613946@bugs.debian.org
Subject: Bug#613946: policy: converted to policy.dbk
Date: Sun, 17 Apr 2011 04:26:43 +0900
Hi,

policy.sgml was successfully converted but I am not sending it over mail
yet.  It may be too big.  It can build nice PDF here.

Osamu
> -- 
> 613946: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=613946
> Debian Bug Tracking System
> Contact owner@bugs.debian.org with problems




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#613946; Package debian-policy. (Sat, 16 Apr 2011 19:36:06 GMT) Full text and rfc822 format available.

Acknowledgement sent to Osamu Aoki <osamu@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 16 Apr 2011 19:36:07 GMT) Full text and rfc822 format available.

Message #53 received at 613946@bugs.debian.org (full text, mbox):

From: Osamu Aoki <osamu@debian.org>
To: 613946@bugs.debian.org
Subject: Bug#613946: perl-policy: converted to perl-policy.dbk
Date: Sun, 17 Apr 2011 04:32:27 +0900
[Message part 1 (text/plain, inline)]
Hi,

Here is for Perl Policy.

Osamu

[perl-policy.dbk (text/plain, attachment)]

Added indication that bug 613946 blocks 661417 Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Mon, 27 Feb 2012 02:15:07 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Sun Apr 20 21:20:32 2014; Machine Name: beach.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.