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

[Alexander Belchenko]

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

John Arbash Meinel пишет:
> 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.

Well, it fixes problems with IE. If people don't want my cross-reference
links -- I can understand. But workaround for IE is critical enough.

> !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?

Because this file already listed in $ALL_DOCS. ostools does not
generate any errors when it cannot delete file already deleted earlier,
it's just for cleaning things up.

> ...
> 
> 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

OK.

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

Oh, sorry. Fixed.

>  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.

Yes, it require comment. The main idea of this code is that docutils
treats section heading as implicit link target. But in some cases
topic and heading are different:

bugs vs. Bug Trackers
working-tree vs. Working Trees

so

.. _topic: `heading`_

is a simple glue between them.

John, thank you for review. I'll resubmit.

- --
[µ]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGuL8dzYr338mxwCURAr9hAJ9oR3lNIITTn+ail7y8ZgJ2vG0VfQCgg44b
BGOgswdmKsoaiYQOcuxQUKE=
=HiLC
-----END PGP SIGNATURE-----