Hi,
Jan Pazdziora has suggested to package HTML documentation instead of the currently commonly packaged INFO documentation.
Wrote the draft proposal for it: https://fedoraproject.org/wiki/PackagingDrafts/HtmlDocs
Are there any comments are can it go for the FPC Trac ticket?
Thanks, Jan
On 02/15/2011 03:59 PM, Jan Kratochvil wrote:
Hi,
Jan Pazdziora has suggested to package HTML documentation instead of the currently commonly packaged INFO documentation.
Wrote the draft proposal for it: https://fedoraproject.org/wiki/PackagingDrafts/HtmlDocs
Are there any comments are can it go for the FPC Trac ticket?
Comments from my part:
1. texinfos need special preparation to be able to convert them to html. This applies to many cases, but does not apply in general.
2. html is just one amongst many formats texinfos can be (if the texinfos have been prepared for) converted to.
I don't see any reason to give html preference over one of the other formats. It's some people's preference, but definitely not all (e.g. I prefer pdf).
3. Many of these html docs are available on-line - Adding local copies to Fedora only adds bloat to the distro
4. The GNU standards's officical documentation format is info.
That said, should FPC vote on this, this proposal will receive a hard and non-negociable NO from my side.
Ralf
On Tue, 15 Feb 2011 16:11:23 +0100, Ralf Corsepius wrote:
On 02/15/2011 03:59 PM, Jan Kratochvil wrote:
Wrote the draft proposal for it: https://fedoraproject.org/wiki/PackagingDrafts/HtmlDocs
Comments from my part:
- texinfos need special preparation to be able to convert them to html.
This applies to many cases, but does not apply in general.
OK, I believe a machine-generated HTML is good enough as the first step. Possible specific problems can be fixed up as normal Bugs later.
- html is just one amongst many formats texinfos can be (if the
texinfos have been prepared for) converted to.
Some list of formats is given on the Wiki page.
I don't see any reason to give html preference over one of the other formats. It's some people's preference, but definitely not all (e.g. I prefer pdf).
I prefer INFO over all the other ones. But I remember I was using HTML before I got used to the only provided INFO. When a separate -doc subpackage is provided I believe providing all the tree of INFO, HTML and PDF is not a problem (HTML as I dislike PDF over the other paging-free formats).
- Many of these html docs are available on-line - Adding local copies
to Fedora only adds bloat to the distro
As we face it on freenode#gdb channel the online versions do not match the local copies. And I do not want to be dependent on network with notebook.
- The GNU standards's officical documentation format is info.
Yes, just Fedora is not GNU.
Thanks, Jan
Jan Kratochvil wrote:
On Tue, 15 Feb 2011 16:11:23 +0100, Ralf Corsepius wrote:
On 02/15/2011 03:59 PM, Jan Kratochvil wrote:
Wrote the draft proposal for it: https://fedoraproject.org/wiki/PackagingDrafts/HtmlDocs
Comments from my part:
- texinfos need special preparation to be able to convert them to html.
This applies to many cases, but does not apply in general.
OK, I believe a machine-generated HTML is good enough as the first step. Possible specific problems can be fixed up as normal Bugs later.
- html is just one amongst many formats texinfos can be (if the
texinfos have been prepared for) converted to.
Some list of formats is given on the Wiki page.
I don't see any reason to give html preference over one of the other formats. It's some people's preference, but definitely not all (e.g. I prefer pdf).
I prefer INFO over all the other ones. But I remember I was using HTML before I got used to the only provided INFO. When a separate -doc subpackage is provided I believe providing all the tree of INFO, HTML and PDF is not a problem (HTML as I dislike PDF over the other paging-free formats).
- Many of these html docs are available on-line - Adding local copies
to Fedora only adds bloat to the distro
As we face it on freenode#gdb channel the online versions do not match the local copies. And I do not want to be dependent on network with notebook.
- The GNU standards's officical documentation format is info.
Yes, just Fedora is not GNU.
Thanks, Jan -- packaging mailing list packaging@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/packaging
Another concern, for those of us with several X-less machines, is that HTML isn't as easy to work with as info or man in a terminal. Why switch from info to html, why not provide both?
-J
On Tue, 15 Feb 2011 16:22:51 +0100, Jon Ciesla wrote:
Another concern, for those of us with several X-less machines, is that HTML isn't as easy to work with as info or man in a terminal. Why switch from info to html, why not provide both?
I suggest to keep INFO and provide _also_ HTML if you read the Wiki page. (BTW as I prefer INFO over HTML myself nowadays.)
Thanks, Jan
On Tue, 15 Feb 2011 16:25:34 +0100 Jan Kratochvil wrote:
On Tue, 15 Feb 2011 16:22:51 +0100, Jon Ciesla wrote:
Another concern, for those of us with several X-less machines, is that HTML isn't as easy to work with as info or man in a terminal. Why switch from info to html, why not provide both?
I suggest to keep INFO and provide _also_ HTML if you read the Wiki page. (BTW as I prefer INFO over HTML myself nowadays.)
Why not just build all documentation available in the upstream tarball and include them? What's available, will be packed, and what not, not manually generated. I think, it should be the choice of upstream.
Or do I misunderstand something here?
-Thomas
On Tue, 15 Feb 2011 16:47:33 +0100, Thomas Spura wrote:
Why not just build all documentation available in the upstream tarball and include them? What's available, will be packed, and what not, not manually generated. I think, it should be the choice of upstream.
Upstream provides `.texi'. You can generate many formats you like.
By default upstream generates only `.info' files which are the only preferred ones by the GNU project. It is an idea this GNU project preference may not match the Fedora users preference.
(We talk about format of the documentation. Various different manuals in each package - such as gdb.info vs. gdbint.info in the gdb package - are not a subject of this discussion.)
Thanks, Jan
packaging@lists.fedoraproject.org
-
Jan Kratochvil -
Jon Ciesla -
Ralf Corsepius -
Thomas Spura