On Fri, Jun 08, 2012 at 03:22:40AM +0200, intrigeri wrote:
> hi,
>
> Chris Frey wrote (08 Jun 2012 00:39:27 GMT) :
> > I've closed all but one, which is the wishlist item for
> > better documentation.
>
> Great!
>
> For everything that follows, I strongly prefer to have such
> a discussion on the bug report rather than privately.
Good idea, thanks. I've kept you in the To: list, but not sure if that
is necessary.
> > Should they have individual -doc packages, or can user and doxygen
> > go into one?
>
> I think we should first ask this question:
> Why would we want to ship doxygen docs in Debian?
It would be useful for developers who want to write applications
based on libbarry. But it is not hard to generate, and it is available
online.
I'm not familiar with Debian's policy on doxygen docs, but from a quick
apt-cache search, it doesn't appear to be a new thing. The ffmpeg-doc
package is about 13M compressed, for example.
> > I don't think a -doc package is really high priority though, since
> > the latest docs will be online anyway.
>
> In general, we want software in Debian to be happily usable even for
> disconnected users, so this is no very convincing argument :)
It was more an expression of my personal time priorities. :-)
It is on my own wishlist as well, not just a Debian bug.
> From my (remote, ignorant) standpoint, I think shipping the small,
> end-user documentation with the software it's about is the right thing
> to do.
I like this idea, but the question is: which package does it belong in?
The user documentation is organized a bit more like a book than a manpage,
and can't easily be split up, nor do I think it is useful that way.
It covers installation, building from source, how to use the backup
program, syncing, troubleshooting, etc. I plan on adding sections for
the Desktop as well.
Not all of it is applicable for Debian, since opensync is not yet
packaged.
Everyone who uses Barry will probably have barry-util installed, since
that's the one with the udev rules. Do the docs belong in there?
Here are the size stats (all HTML docs):
User docs, uncompressed: 350K
Doxygen, without dot graphs, uncompressed: 12M
compressed: 875K
Doxygen, with dot graphs, uncompressed: 79M
compressed: 56M
The dot graphs are optional... basically look nicer and are sometimes
easier to read. Doxygen uses HTML instead when dot is disabled.
I think a barry-doc package for the user docs would work. That would
leave the libbarry-doc name for doxygen docs later, if needed.
Let me know what you think.
Thanks,
- Chris
--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
