Re: Documentation formats
Ian Jackson: I'm not certain that distributing HTML with the packages and other formats separately is a good idea. I think it might be a better idea to continue as now and use on-line conversions from man and Info to HTML. Pre-converted HTML should be distributed as separate packages. So you'd rather I put the SGML source for the manuals in the dpkg binary package, rather than the HTML pre-converted form ? No, I was talking about man and Info, in my usual unclear fashion, sorry. The conversions of man and Info to HTML are fairly fast. -- 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. pgpXJhJp2w2Ky.pgp Description: PGP signature
Re: Documentation formats
Lars Wirzenius writes (Re: Documentation formats ): ... I'm not certain that distributing HTML with the packages and other formats separately is a good idea. I think it might be a better idea to continue as now and use on-line conversions from man and Info to HTML. Pre-converted HTML should be distributed as separate packages. So you'd rather I put the SGML source for the manuals in the dpkg binary package, rather than the HTML pre-converted form ? Conversion of things into HTML is particularly awkward because you end up with lots of intermediate files. And, my debiandoc-sgml converters are not exactly fast. Converting the dpkg manuals to plain text takes about 5 minutes on my Cx5x86/120 (clock-tripled 40MHz). This is about 50% of the time it takes to build a whole new release of dpkg (the HTML converter is much faster). Ian.
Re: Documentation formats
Mark Eichin writes (Re: Documentation formats): [Ian asked:] (Is texi2html any good?) http://www.cygnus.com/ (and I'm sure other places) has texi2html'ed versions of gnu compiler-related tools, if you want a quick look at them. Thanks. They do look reasonable. Ian.
Re: Documentation formats
Mark Eichin writes (Re: Documentation formats): if we standardize the names for the alternate formats, can we also have, for each format foo, a virtual foo-viewer package, and include it in the dependencies? (That will, as a side effect, make it easier to determine which formats are supported in a given package...) It looks like we don't have a consensus or indeed a technical basis for a decision on documentation formats, so we'll keep the current ad-hoc arrangements for the moment. When we go for a more formalised scheme this sounds like a good idea. Ian.
Re: Documentation formats
Or do we do some kind of display-time conversion from info to HTML ? This is probably best. Thanks Bruce -- Clinton isn't perfect, but I like him a lot more than Dole. Please register to vote, and vote for Democrats. Bruce Perens AB6YM [EMAIL PROTECTED]http://www.hams.com/
Re: Documentation formats
Bruce Perens writes (Re: Documentation formats): From: Ian Jackson [EMAIL PROTECTED] The thing is that I think we need to be able to distribute other [documentation] end-products [than HTML]. HTML is bad for printing, for example, and not ideal if you have a slow machine. Choice is a good thing. Do you have a proposal? I'm not trying to exclude other formats, but I'm trying to arrive at a common denominator, even if it has its detriments. Yes, fine. I think we're in agreement. I'll post my proposal in another message. I'm not sure I agree with the slow machine part. That seems to be browser-specific. Well, even lynx is much slower than less, and has a worse user interface in some people's eyes. Ian.
Re: Documentation formats
Bruce Perens writes (Re: Documentation formats): ... The unification of Debian documentation will be carried out via HTML. You should not consider the merits of a particular HTML viewer, or even the weight of the best of our existing HTTP servers. These things will change with time, and without effort on our part. Instead, you should concentrate in providing automatic means to present man files, info files, and other various forms of documentation to the user. This can be done at run-time via CGI scripts, or when the documentation packages are installed. Use existing software where possible. Try to consider disk space, but having a full documentation system takes priority over that. A keyword search facility and a unifying set of indices are a high priority. Texinfo-generated info files are very common for obvious reasons. Do we start distributing Texinfo-generated HTML instead ? (Is texi2html any good ?) Or do we do some kind of display-time conversion from info to HTML ? Or leave the question for the moment ? Ian.
Re: Documentation formats
Bruce Perens writes (Re: Documentation formats): From: Ian Jackson [EMAIL PROTECTED] The thing is that I think we need to be able to distribute other [documentation] end-products [than HTML]. ... Do you have a proposal? ... My initial proposal is as follows: If it's available we distribute HTML documentation with the package itself (if the documentation is usually distributed with the package) or in the main documentation package package-doc (if it wants to be distributed separately, for example because it's large). Other formats are distributed in separate packages package-doc* where * is some string. We can either put them all together, keeping the number of packages small, or have one package per format, making it possible to install formats selectively. If we do former the * should probably be `xf' (extra formats) or `fmts' (formats) or some such; if we do the latter it should represent the format (`dvi', `ps', `text', whatever). We can do a mixture of the two, specifying that one or two specific formats should be supplied in their own packages, or allow the package maintainer to decide, or set size-based guidelines, or whatever. Opinions and arguments, anyone ? Ian.
Re: Documentation formats
From: Ian Jackson [EMAIL PROTECTED] The thing is that I think we need to be able to distribute other [documentation] end-products [than HTML]. HTML is bad for printing, for example, and not ideal if you have a slow machine. Choice is a good thing. Do you have a proposal? I'm not trying to exclude other formats, but I'm trying to arrive at a common denominator, even if it has its detriments. I'm not sure I agree with the slow machine part. That seems to be browser-specific. Thanks Bruce
Re: Documentation formats
Ian, I am aware of your efforts with linuxdoc.sgml, and I think it's important to make it clear that HTML is only the end-product. It's fine to encourage people to use linuxdoc as a source language. Thanks Bruce
Re: Documentation formats
Rob Browning writes: Lars Wirzenius [EMAIL PROTECTED] writes: I don't think we have free software packaged to do full text searches. We have glimpse and ferret, neither of which is free. There's something that is part of freeWais, but I haven't looked at it yet. Someone with the time should find and package one. It should be usable from the command line so that it can easily be integrated into Debiandoc. It'd be nice to have something like altavista, that could generate a page containing a (heirarchical) list of the references found. The search program ht://Dig (which has an admittedly odd name) comes with the GNU general public license. Its home page is: http://htdig.sdsu.edu/ Also, there's been a Javascript on comp.infosystems.www.authoring.cgi that uses the Altavista search engine to search only your own site. (Seems like exploiting rather than excluding robots.) Regards, Susan Kleinmann
Re: Documentation formats
Someone: IMHO info is a great format. From: [EMAIL PROTECTED] (Kai Henningsen) Actually, I have just about the same problems with info that you have with lynx - it's ugly, it has a *really* arcane user interface. *** Project Leader Fiat Power On *** The unification of Debian documentation will be carried out via HTML. You should not consider the merits of a particular HTML viewer, or even the weight of the best of our existing HTTP servers. These things will change with time, and without effort on our part. Instead, you should concentrate in providing automatic means to present man files, info files, and other various forms of documentation to the user. This can be done at run-time via CGI scripts, or when the documentation packages are installed. Use existing software where possible. Try to consider disk space, but having a full documentation system takes priority over that. A keyword search facility and a unifying set of indices are a high priority. Look at what Ray Dassen has done on our web site. That is a really good start. Now think of the top-level index to Debian documentation coming up in a web browser when the new user starts the system. *** Project Leader Fiat Power Off *** Thanks Bruce
Re: Documentation formats
Bruce Perens: The unification of Debian documentation will be carried out via HTML. I assume the unification won't mean that the native formats aren't supported -- they _do_ have benefits. That said, I fully agree with choosing HTML. Debiandoc, supports on-line conversions to HTML from man and text, and info2www supports Info (it isn't really integrated, but it's not really visible). The converters are configurable. In addition, I think we should provide texi2html'd documentation in addition to Info files. texi2html seems to do a better job than info2www. A keyword search facility and a unifying set of indices are a high priority. I don't think we have free software packaged to do full text searches. We have glimpse and ferret, neither of which is free. There's something that is part of freeWais, but I haven't looked at it yet. Someone with the time should find and package one. It should be usable from the command line so that it can easily be integrated into Debiandoc. -- Lars Wirzenius [EMAIL PROTECTED] http://www.iki.fi/liw/ Please don't Cc: me when replying to my message on a mailing list. pgppOuFX80wNS.pgp Description: PGP signature
Documentation formats
I've just added the subsection below to the draft policy manual. Bruce, tell me if you want me to say something different. I'd like to come up with some rather more formal way of distributing our different documentation formats. Perhaps we should create a new subdirectory of the FTP site for packages' PostScript documentation and upload it separately. Alternatively we could recommend that if a package can produce documentation in n formats it should put the HTML in with the package itself (if it doesn't warrant a separate package) but put the other n-1 together in a separate package which uses some canonical naming scheme. Eg, dpkg - contains the programs and the HTML documentation dpkg-docxf - contains the documentation in ps, plain text c or texinfo- contains the Texinfo formatter itself texinfo-doc- contains the documentation run through texi2html texinfo-docxf - contains the docs in /usr/info, and as dvi If we do this we should probably say that if a package produces dvi as its native format we should ship dvi and not ps. Ian. sect1Preferred documentation formats The unification of Debian documentation is being carried out via HTML. p If your package comes with extensive documentation in a markup format that can be converted to various other formats you should if possible ship HTML versions in the binary package, in the directory tt/usr/doc/var/package// or its subdirectories. p Other formats such as PostScript may be provided at your option.
Re: Documentation formats
LW == Lars Wirzenius [EMAIL PROTECTED] wrote: LW Ian Jackson (after my deletions): * GNU Texinfo ... HTML. * The Linux FAQ ... HTML ... * The Linux HOWTOs ... HTML ... * My new dpkg manuals ... HTML ... * The Perl documentation ... HTML LW I think I see a trend here. While HTML is not the perfect format (e.g., LW it lacks the navigation hints in Info), it is still the only LW common There is a great advantage of info over html: you can search an entire document with it. I think this is fundamental. LW denominator, and I guess most people will have a web browser LW installed anyway. People who have standalone machines might not want to install a www browser. Lynx is ugly (JMHO). Can't really use it. Nevertheless, I must be able to read docs in text mode. IMHO info is a great format. After reading some discussion on gnu.misc.disc I'm pretty convinced that it's currently the best format for online docs (and don't forget texinfo files can also generate printed manuals) and that we should try it a bit more. The real problem are the info browsers. The last version I checked of the standalone info program simply sucks. Maybe someone with a good knowledge of termlib should take a look at it. Maybe add some mouse support via gpm? What about xinfo? Is this any good? Yes, I know there is tkinfo, but it needs tcl/tk... Ciao, Emilio. -- Emilio C. Lopes mailto:[EMAIL PROTECTED] Instituto de Fisica da Universidade de Sao Paulo Caixa Postal 66318, 05389-970 Sao Paulo - SP, BRAZIL Phone: (+55) (11) 818-6724 (Voice) / 818-6715 (Fax)
Documentation formats
Increasingly, documentation is in a generic markup format that can be processed into various output formats either by standard tools or ones that come with the package. For example: * GNU Texinfo can be converted to Info, DVI (and hence rather large PostScript) and HTML. * The Linux FAQ comes in plain ASCII, HTML, Info, and PostScript via Lout. * The Linux HOWTOs are done in linuxdoc-sgml, which produces ASCII, HTML, Info and LaTeX (hence DVI and large PostScript). * My new dpkg manuals will be available in plain ASCII, overstruck ASCII, HTML and Postscript (via Lout). * The Perl documentation can be converted to HTML, plain text, manpage source (hence overstruck text and PostScript) and LaTeX (hence DVI and large PostScript). We need to decide which documentation formats we wish to distribute, and how to manage their display. Obviously we can't distribute all of the output formats as that will either make packages too large or produce too many packages. For some of the formats you can process the data `on the fly' as it is viewed; for others (at least TeX, Lout and HTML) this is trickier as the processing or viewing involves dumping the formatted document to a file, or storing some kind of auxiliary data in files while it's being processed. Options for our policy include: 1. Specify one or two particular preferred target formats and distribute those. Leave the source in the source package. So far we have done this with documentation in Texinfo - we leave the .texi files in the source package and distribute only the info files. 2. Distribute the source only and a converter. This has been done with manpages, and with the Perl `pod' documentation. 3. Distribute the source and one target format for people who don't have or want converters. 4. Do something fancy with Lars's documentation viewing stuff. I'm sure Lars will tell us about this. My inclination is to go for 4 with 2 or 3, if that makes sense. Ian.
Re: Documentation formats
Ian Jackson (after my deletions): * GNU Texinfo ... HTML. * The Linux FAQ ... HTML ... * The Linux HOWTOs ... HTML ... * My new dpkg manuals ... HTML ... * The Perl documentation ... HTML I think I see a trend here. While HTML is not the perfect format (e.g., it lacks the navigation hints in Info), it is still the only common denominator, and I guess most people will have a web browser installed anyway. We must still support the native versions. Not everyone will want or prefer a web browser over Info or manual pages. Debiandoc can handle on-line conversions. Some of the conversions aren't too good. For example, texi2html seems to do a better job than info2www, and I'm told this is inherent. Thus, it would be a good idea to provide texi2html'd versions of the Info files as optional packages. The FAQ's, HOWTO's, and other such stuff should also be made available as optional HTML versions, if one is currently not part of the main package. Summary: status quo, but provide optional HTML packages. This leaves us with the problem of having the same documentation in several formats installed at the same time, which is usually a waste of disk space. This is solvable with some programming: provide tools to identify and remove duplicate documents. It's a SMOP, as long as I don't have to do it. :-) -- Lars Wirzenius [EMAIL PROTECTED] http://www.iki.fi/liw/ Please don't Cc: me when replying to my message on a mailing list. pgpCvVbjf1Aky.pgp Description: PGP signature
Re: Documentation formats
Options for our policy include: 1. Specify one or two particular preferred target formats and distribute those. Leave the source in the source package. So far we have done this with documentation in Texinfo - we leave the .texi files in the source package and distribute only the info files. 2. Distribute the source only and a converter. This has been done with manpages, and with the Perl `pod' documentation. 3. Distribute the source and one target format for people who don't have or want converters. 4. Do something fancy with Lars's documentation viewing stuff. I'm sure Lars will tell us about this. My inclination is to go for 4 with 2 or 3, if that makes sense. And get rid of the .info files, using w3-el on texi2html .texi files. Sorry but this isn't very fast on an 8mb machine. It might be that I don't understand the above, but for me w3-el via texi2html on the fly is a very fast and therefore unwanted alternative for the info-reader in emacs. I presume quite some others agree with me. Erick
