[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Info or HTML: which should be the default, which in a separate package?



[ Please don't Cc: public replies to me. ]

Dirk Eddelbuettel:
> But they get html via the dwww package! Which gives them _more_ documentation
> then there is in html only.

dwww uses info2www. The result of converting Info to HTML with
info2www is unacceptably bad. For example, it doesn't reformat
the text when the browser window is resized, or highlight
headings in the way proper HTML does. It's just barely good
enough to serve during a transition period. Converting directly
from Texinfo source code to HTML with texi2html gives acceptable
results.

It is not the fault of info2www that the result is bad. Info
just isn't a format that it is reasonable to convert from.

If we want to have all documentation browsable via a single
interface, which as far as I know we still do, then HTML is
the only viable alternative, and lousy HTML is not acceptable.

> Seconded. Nobody answered my mail from yesterday which showed that the
> doc-linux package will take up over 5 MB (instead of 1.6 MB) for the html
> stuff.

There's no reason why HTML should be much bigger than Info. I assume
you used uncompressed HTML. There's no inherent reason why HTML can't
be compressed; the only reason it isn't is that links break, but that
is fixable. dwww already fixes it by giving you foo.html.gz if it exists,
and foo.html doesn't exist. (That conversion doesn't help if you don't
browse via dwww, but that's a minor blemish. We need a tool to fix the
HTML files, but dwww's fix makes it less urgent.)

What's the difference if you do "gzip -9 *.html"?

> No way. IMHO, we should add a Policy Guideline stating that html should be in
> a seperate package [1] and that info should be shipped as usual.

That's one way of doing it. The other way is to have Info as a
separate package, which may or may not be a better alternative
(it's better for me; if I never, ever see an Info file again,
I couldn't be happier). Anyway, we need both. At the moment,
many packages don't seem to have an HTML version, just an Info
version, of the documentation. For political reasons (read:
Emacs users scream too loudly :), I assume we must put HTML
in a separate package, _but_ _it_ _must_ _be_ _there_.

> Make it an option to add html docs, but don't make it compulsory.

HTML docs must be compulsory, because info2www is not an acceptable
alternative.

>   Scott>  Okay, show me how to search a HTML version of the bash info
>   Scott> documentation for a concept and I'll believe you.

Searching in HTML requires a separate program, which we don't yet
have. That's one place where Info is better. For now. (When we get
a search engine for dwww, it will be able to search through all
documentation, not just a single document. But it will be quite some
time until we get it, I think.)

-- 
Please read <http://www.iki.fi/liw/mail-to-lasu.html> before mailing me.
Please don't Cc: me when replying to my message on a mailing list.


Attachment: pgpY2V8GyF1Wx.pgp
Description: PGP signature


Reply to: