Re: [Gnumed-devel] GnuMed documentation (Was: GNUmed 1.1.9 Maintenance Release)

[Andreas Tille]

On Fri, Jan 13, 2012 at 03:04:40PM +0100, Sebastian Hilbert wrote:
> > The exact problems are:
> >   - Broken Links
> >   - Ugly and finally for the content totally irrelevant header image
> >   - A lot of pretty useless JavaScript stuff
> >
> 
> Apart from the Javascript stuff all other problems are fixed. Why again is 
> this 
> javascript stuff (apart from the chat widget) an problem again ?

Well, it certainly is JS no problem in general.  I just wanted to say,
that if I were in the shoes of Joe GNUmeduser would be quite bored about
windos poping up at random if I want to quietly read some docs.  That's
not about Debian - that's about my users.  However, that's no real
reason to refuse the doc package.

> I would like to know the exact requirements for docs in Debian to become 
> acceptable or even good docs. Is html with JS not acceptable ?

It might be that lintian will tell me to prefer some Debian packaged JS
libraries instead of those shipped with your tarballs which makes sense
from a security point of view but this is not your concern as upstream.

> We could provide pdf if that is better.

I would not formulate it that harsh as Karsten because you could ship
the HTML as source in parallel, but no, it's not really better.  If you
try to consider the "typical reader of the documentation" and think he
would prefer PDF and it is not hard to provide this it might be an
additional option.

<that's-not-me-who-is-burning-tropical-rainforest>
Finally a PDF can be more easily printed and I learned that doctors
love their printer very much.
</that's-not-me-who-is-burning-tropical-rainforest>

Or come on - perhaps e-book readers are better in displaying PDF.  If
you consider these ideas and would like to add a PDF in addition to the
HTML, that's fine (if it comes cheap technically).
 
> Find attached the current state of affairs.

Looks *way* better.  While the doc finally has the same size it has
*useful* images like screenshots and is featuring the real content
properly.  Well, done - I'm happy.  The only hint which could be
enhanced is an additional

   ln -s GnumedManual.html Gnumed/index.html

I don't mind whether you do this inside the tarball because I can
perfectly easy do this in the Debian package - however it might be some
comfort for non-Debian users.  (I have noticed your intention in the
1.1.9 package but it just needs to be done in the same directory as the
other docs to keep the links working.)

Thanks on for your work on this issue.  Looking foreward to package
1.1.10

      Andreas.


-- 
http://fam-tille.de