[MERGE] Pretty docs with Kid

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

John Arbash Meinel wrote:
> 1) This means you depend on 'kid', right? I realize it is a separate
> tool, and not core bzr, but it is another dependency.

It is, and that's why I'm not proposing it as a replacement for the
standard reST output.

> 2) Please don't strip all the <a> tags. We may need to update the
> stylesheet, but it is *really* nice to reference a specific subsection.
> http://doc.bazaar-vcs.org/bzr-0.11/configuration.htm#location-of-configuration-file

Oh, I agree.  But Matt doesn't seem to have made any updates in some
time, and there's a long list of requests:
http://bazaar-vcs.org/BzrWebsiteComments

Anyhow, it was partly to show that kid is powerful enough to do this.
There are other ways.  Inline syle attributes, inline stylesheets, etc.

> 3) What inappropriate links?

- - AaronBentley
- - User Preferences
- - FindPage
- - RecentChanges
- - Edit Page
- - Page History
- - Subscribe
- - More Actions

> The reason the links are '.htm' is because that is what is generated. I
> assume because Alexander is more used to Windows development where .htm
> is frequently preferred to .html. But if you look at the website: 'make
> html-docs' generates:
> http://doc.bazaar-vcs.org/bzr-0.11/configuration.htm

Right.  I had anticipated that 'make pretty-html-docs' would generate
'configuration.html', so that the two sets of docs could coexist.

> Also, this looks pretty bad:
> +   def fixlink(attrib):
> +      attrib = dict(attrib)
> +      attrib['href'] = attrib['href'] + 'l'
> +      return attrib
> 
> Since it assumes everything ends in '.htm' if you had one that was
> '.html' you would get in pretty big trouble.

That action should only be applied to tags that match this rule:

      if item.tag != '{http://www.w3.org/1999/xhtml}a':
         return False
      elif 'href' not in item.attrib:
         return False
      elif item.attrib['href'].startswith('http://'):
         return False
      elif item.attrib['href'].startswith('/'):
         return False
      elif not item.attrib['href'].endswith('.htm'):
         return False

> I really like that the output looks the same as the rest of the
> documentation, so I'm happy with most of the result. (Especially since
> we seem to keep forgetting to put default.css into the right directory,
> though I emailed Martin about it).

> I also think the Wiki css is probably nicer than our customized css in
> general. We probably should copy it across, so that standalone
> documentation gets the same css. (Especially since Alexander bundles the
> documentation with his Windows Installer).

I don't know how well that would work, but I guess we could try it.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFFHZB+0F+nu1YWqI0RArLUAJ0SUzGG9aNC1uYUBdWzBahx+N0XawCaA7Ap
W5SQIBPnWOXUrZZSmQhAiaA=
=i/yZ
-----END PGP SIGNATURE-----