[PATCH][0.19] IE-safe bzr_man.html and cross-reference links for see also

[John Arbash Meinel]

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

Alexander Belchenko wrote:
> /me continue to reply myself.
> 
> New better patch that create cross-reference links for 'see also' topics.
> I think it's improve usability a lot.
> 
> Resulting page is here: http://bzrdev.bialix.com/bzr_man.htm
> 
> (Let's looking at this beauty and don't hesitate to print.
> I think Ian did incredible job to improve this page,
> and I hope my small changes make the picture a bit better).
> 
> [µ]

I'll leave it up to James to decide if this is 0.19 worthy.

!tweak

...

 doc/bzr_man.txt: $(MAN_DEPENDENCIES)
@@ -127,7 +128,7 @@
 # clean produced docs
 clean-docs:
 	python tools/win32/ostools.py remove $(ALL_DOCS) \
- -	$(HTMLDIR) $(PRETTYDIR) doc/bzr_man.txt doc/developers/performance.png
+	$(HTMLDIR) $(PRETTYDIR) doc/bzr_man.txt

^- why aren't you removing performance.png if it was generated?
I don't know how ostools is defined right now, but I would hope we can
continue even if a file/directory doesn't exist.
Otherwise we can move it to another line with

  -python tools/win32/ostools.py remove doc/developers/performance.png

The '-' tells Make that it should ignore whether the command succeeds or
fails.


...

v- This "if X and Y or Z" structure was a bit hard to understand for me.
I think it might be better to just spell it out.

see_also_links = []
for item in see_also:
  if item == 'topics':
    # topics doesn't have an independent section
    # so don't create a real link
    see_also_links.append(item)
  else:
    # Use a reST link for this entry
    see_also_links.append("`%s`_" % (item,))
see_also = see_also_links



v- "Written by the Bazaar community"

- -Written by Alexander Belchenko and the Bazaar community.
+Written by Bazaar community.
 """

 import os
@@ -68,6 +68,7 @@
     """Build the manual part from topics matching that section."""
     topics = sorted(registry.get_topics_for_section(section))
     lines = [title, hdg_level1 * len(title), ""]
+    links_to_topics = []
     for topic in topics:
         help = registry.get_detail(topic)
         heading,text = help.split("\n", 1)
@@ -75,6 +76,9 @@
         lines.append(hdg_level2 * len(heading))
         lines.append(text)
         lines.append('')
+        if topic != heading.lower():
+            links_to_topics.append((topic, heading))
+    lines.extend([".. _%s: `%s`_" % i for i in links_to_topics])
     return "\n" + "\n".join(lines) + "\n"

^- This seems a little odd. You are defining a link to point to a
different link. So if someone uses `topic`_ they end up diverted to
`heading`_. At least if I understand this correctly. Is that true?
At a minimum, it probably needs a comment.


John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGuLdkJdeBCYSNAAMRAtevAJ9wepOQktQcZItlstvGWKRgTjPBPACdHzC9
DZHK5La0+VrKuOc79BER6V0=
=XMZj
-----END PGP SIGNATURE-----