Documentation in 0.11rc1

[John Arbash Meinel]

Alexander Belchenko wrote:
> Document 'Centralized Workflow' (bzr.dev/doc/centralized_workflow.txt)
> seems to be unfinished and has 1 unresolved internal link:
> 
> python tools/rst2html.py --link-stylesheet --stylesheet=default.css
> doc/centralized_workflow.txt doc/centralized_workflow.htm
> doc/centralized_workflow.txt:83: (ERROR/3) Unknown target name:
> "xxxreferenceconversionofhistory".
> 
> Also this document was not added to index.txt, therefore it hidden from
> documentation index (when html docs installed on windows or will be
> uploaded to canonical server).

Well, it was semi-incomplete, hence I didn't hook it into the rest. I
hadn't gotten a huge amount of feedback, but I felt it was better to get
it in, than to leave it out.

I don't know of a good reference for conversion of history, yet. Hence
why that link isn't resolved.

This is the best one I could find:
http://bazaar-vcs.org/TrackingUpstream

Though I wrote that one as well, and it isn't super perfect either.

> 
> Is this document intended to be visible in 0.11 release or not?

I don't think back-porting fixes to make it visible is really worth a
new release candidate.

> 
> If yes, then I ask John, as author of this document, -- please, do
> something with unresolved link.
> 
> Also I want to say that Readme.1st is mostly duplicate content of
> index.txt. Do we need keep this readme up-to-date or rework them to
> point to index.txt?
> 
> -- 
> Alexander

I would probably have README.1st reference index.txt. I'm tempted to
just remove it. Or maybe change it to README.txt, and then have it have
*identical* contents to index.txt.

Or could we have 'make docs' know to change README => index.htm?

index.html is good for web browsing (though it doesn't make any
difference on the local filesystem), but people reading text
documentation aren't going to know to look there. And having a stub file
 telling you to look at another file is a little ugly.

I would also get rid of all of the disclaimers about being out of date.
These docs are *meant* to be the version specific documentation.

So....

README.1st should be cleaned up. At this point I'm okay with just
removing almost everything and telling them to switch to index.txt.

John
=:->

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 254 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060926/f69bf398/attachment.pgp