On 07.01.2011 22:28, Jonathan Nieder writes:
>>> If I list all three files in three lines, it will result in an
>>> installation error:
>>
>>> Format: text
>>> Files: /usr/share/doc/fcitx/Develop_Readme
>>> /usr/share/doc/fcitx/API.txt.gz
>>> /usr/share/doc/fcitx/pinyin.txt
In general, the `Files:' field can contain a multi-line value, and
doc-base correctly reads such value, and internally stores the value
separated by new lines.
>
> $$format_data{'files'} would contain "/foo\n/bar\n/baz".
Yes, and while registering to scrollkeeper it tries to check if the file
exists using `next unless -f $_' and skips the registration if it
doesn't. Unfortunately this causes perl to emit some warning (see output
of `perldoc perldiag | grep -A 3 "containing newline"' for motivation).
When you change your multi-line Files field into a single-line one, the
warning is gone, but still your documentation won't be registered into
scrollkeper (as the "/foo /bar /baz" file don't exist either).
> Separate question: is Text documentation allowed to have an index?
> If not, how should one get started in reading some text documentation
> listed in /usr/share/doc-base?
And this is the main problem here - how doc-base or other tools should
handle documentation consisting of multiple text documents? I've just
checked how your doc-base file is showed by the available front-ends, and:
- dhelp shows the first file (/usr/share/doc/fcitx/Develop_Readme) only
- dwww ignores your doc-base file entirely
- doc-central fails to show the documentation, because "The requested
URL /doc/fcitx/Develop_Readme /doc/fcitx/API.txt.gz
/doc/fcitx/pinyin.txt was not found on this server."
The similar problem exists in case of doc-rfc-* packages, that registers
entries like this:
Format: Text
Files: /usr/share/doc/RFC/informational/*.txt.gz
Also in this case, none of the available frontends is able to handle
such entries. (To be honest I've just came up with some idea how to show
those entries to the user - namely by generating some page with links to
all registered files - I'll try to implement this solution in dwww at
spare time).
And no, documentation in Text format, isn't allowed to provide index
files - for the very similar reasons: the frontends would show the index
files only, skipping the other registered files. For the HTML format the
assumption is that user would be able to navigate from the index file to
the other files.
Anyway, I think in case of fcitx package, it should probably register
the text documents in 3 different doc-base files, but honestly I'm under
impression that the documentation is useful for the package developers
only, but I might be wrong, especially because I don't understand
Chinese at all. Also in my opinion the Abstract (`describes what fcitx
is and how it can be used.') and Section ('Help/Books') fields should be
also changed to something more appropriate.
>
> It is optional but presumably the scrollkeeper entry would not be very
> useful for yelp without it. But wait --- do the graphical help tools
> even use OMF any more? Perhaps we should be targetting rarian
> directly?
I could switch to rarian, when I learn how to do this. I've just checked
that doc-base registered scrollkeper documentation no longer shows up
neither in yelp nor in khelpcenter on my system, so it seems sth I'll
need to do the switch soon.
Regards,
robert
--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
