Documentation in 0.11rc1
John Arbash Meinel
john at arbash-meinel.com
Tue Sep 26 15:35:55 BST 2006
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:
> 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:
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?
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.
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.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 254 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060926/f69bf398/attachment.pgp
More information about the bazaar