On Sat, Jan 26, 2008 at 01:12:13PM -0700, Bob Proulx wrote:
Unfortunately then there is the problem of upstream documentation and downstream stable release programs being out of sync with each other. There would be the potential for bts reports from users saying such and such a feature is documented (in a later version) but not implemented (in the stable version).
Yeah, I started to write that in my previous email then deleted it. :)
Would Debian consider creating a web location for web documentation that matches the Debian releases? That would solve the issue. (And create one of needing to keep the web docs up to date out of band from package updates.)
I considered that and thought up the same sort of objections. I think there would be a lot of value in some sort of web interface which had the coreutils info docs for each version, so it could be referenced as something like http://coreutils.docs/manual/6.10/html_node/cat-invocation.html#cat-invocation
Yeah, it's an ugly URL, but so is watching a new user trying to figure out info(1)...
I guess this should actually be fairly easy to automatically extract from the VCS. It might even be possible to host this somewhere in the debian infrastructure.
Or alternatively create a coreutils-doc-html package so that these can be locally installed by the end user? I think that would be better if the goal is to provide html documentation. Then updates to it would occur naturally as the package was updated. Then something like the following would provide a browser location for the user. file:///usr/share/doc/coreutils/html/index.html
That's another possibility. I think that in practical terms there are *at least* as many people who might want to look at the docs while they're logged into a remote host (making it kind of ugly to access that sort of path) as there are without internet access & a web browser.
I personally am an info user so take these suggestions as coming from someone who wouldn't be using the html docs anyway.
I'm one who can't stand the info(1) program. :-) There are other interfaces (one of which I use) but that's too big a topic to fit in the man page. It's a shame that the texinfo docs have such an unapproachable front end; I do think it's telling that we get so many bugs based on the man pages for which the answer is "read the info docs"--I think there's a reason that people aren't reading the info docs. (The current brokenness in debian doesn't help, but this was true even when the debian info setup worked.) Anyway, I think we would see more people read those docs if it were easier to get to them with a less opaque interface.
Mike Stone -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
