Mailinglist Archive: opensuse-features (365 mails)

< Previous Next >
[openFATE 306404] Provide access to manuals
  • From: fate_noreply@xxxxxxx
  • Date: Wed, 10 Mar 2010 15:21:03 +0100 (CET)
  • Message-id: <feature-306404-47@xxxxxxxxxxxxxx>
Feature changed by: Karl Eichwalder (keichwa)
Feature #306404, revision 47
Title: Provide access to manuals

openSUSE-11.2: Rejected by Gary Ekker (michl19)
reject date: 2009-12-10 16:21:53
reject reason: 11.2 is past
Priority
Requester: Important

openSUSE-11.3: Done
Priority
Requester: Mandatory

Requested by: Frank Sundermeyer (fsundermeyer)
Developer: (Novell)

Description:
In openSUSE 11.1 it is almost impossible for a regular user to access
the official manuals.
By default, only the complete set of HTML manuals is installed, while
the PDFs are not installed by default. There is no way of easily
locating the packages containing them unless you know the package
names. In order to improve this
* the term "manual" has to appear in the package name or at least in
the summary of the package
* a Pattern "Manuals" is needed
Theoretically the HTML manuals should be accessible via the KDE or
GNOME help center. In the past the help centers have made lots of
trouble when integrating the manuals, so they almost always were either
not available in KDE or GNOME. Since the release of KDE4, for example,
they can no longer be integrated into the KDE help center. Apart from
that, the help center has certain disadvantages:
* no proper search within the manuals
* too many clicks are needed to access a manual
* not printable
* users of other GUIs have no easy access to the manuals (via the
filesystem only)
Therefore the PDFs have to be installed by default, too. Additionally
an entry "Manuals" with links to the PDFs has to be added to the main
menus of the GUIs (KDE, GNOME, XFCE,...).
Furthermore, the manuals are not accessible directly from the media
(the start-up guide being the sole exception), so one can only use them
after having installed the system. Therefore providing Installation an
Quickstart Guide is kind of absurd. I propose to host the PDFs under
/docu in all repositories and create "empty" RPM packages just copying
the PDFs from there.

References:
https://bugzilla.novell.com/show_bug.cgi?id=587031
https://bugzilla.novell.com/show_bug.cgi?id=586682

Documentation Impact:
Evaluate if RPMs can postinstall the unpacked PDFs from the install-
Media

Discussion:
#1: Michael Löffler (michl19) (2009-06-05 16:15:21)
Having the manuals accessible in the Help Center is sufficient, adding
pdfs imo just nice to have.

#2: Frank Sundermeyer (fsundermeyer) (2009-12-01 16:39:11) (reply to
#1)
As I pointed out in the initial description: Since the release of KDE4 the
manuals are no longer available from the KDE help center.

#3: Juergen Weigert (jnweiger) (2009-12-01 17:26:58)
This request comes from doc-team and doc-team will implement it. The
request is only here to synchronize efforts.
I see the following defects: - we obsolete old docu packages with
opensuse-manuals_en, but do not require the set of new packages. So
nothing is currently installed. - user has to guess package names and
activly hunt for the packages. do we have a reason for not installing
docs? Disc space should not be a limitation. - installation manual
should also be unpacked in the root directory of the install medium.
RPM package for the installed system also has a copy of this. Look into
a more clever RPM package. - create appropriate mene entries. (desktop
files?) - place a doc-icon on the plasma desktop (decide if we have PDF
or HTML there?) - integrate searchable docs in the startup menue search
engine.
I see no reasons for not doing any of the above. PM, please advise.

#4: Karl Eichwalder (keichwa) (2009-12-02 08:04:28)
HTML in KDE4: According to
https://bugzilla.novell.com/show_bug.cgi?id=391185 it finally worked on
11.1 (maybe, there is still a confusion with KDE3 and KDE4). A KDE
expert must check this please and tell us how the desktop files must
look alike and where we should install them.
Installing PDF by default: Sometime ago we were told that we should
not clutter the user's disk with install two falors of our manuals and
that HTML would be the better choice. In earlier times the PDFs used to
be unpackaged on the media, though. Aside: I'd rather prefer Info files
(and PDFs), but that's a different story.
Invisibility of the docs: There is quite some noise about the books in
the wiki (and on novell.com/documentation). If you ask google about
"opensuse documentation" or "docs", en.opensuse.org/Documentation is
the first hit. It looks a little bit different, if you use "manuals"
instead of "Documentation", but still fine.
Label or Summary of the package description: I just stick with the
book title (modulo bugs). Everything else will lead to confusion. These
days, package metadata are either kept in BS config files or in our
special attributes" files. I would be fine with me, if some human being
or an automatic make command would maintain the attributes file.

#7: Juergen Weigert (jnweiger) (2009-12-03 19:24:29) (reply to #5)
I added SP1 - I know this is a late feature, and I should file such
requests. Sorry. Let us please have some improvement to the current
situation in SP1. Minimum effort for SP1 is adding appropriate desktop
files. Do we have approval here?

#6: Karl Eichwalder (keichwa) (2009-12-03 14:13:31)
This is a related feature: fate#306322 Accessing PDFs from within the
help centers

#10: Juergen Weigert (jnweiger) (2009-12-04 15:24:27)
Karl, Stefan pointed me to /work/SRC/all/sled-gnome-cbt_en/ *.spec cbt.
desktop implements an icon on the GNOME desktop. Is this helpful? Are *.
desktop files menat to be KDE or GNOME specific... ? :-(

#13: Karl Eichwalder (keichwa) (2009-12-07 10:18:31) (reply to #10)
Putting Icons an the desktop is something different. .desktop files are
general (see freedesktop.org), but vendor enhancements are possible.
Maybe, we should split theis feature. ATM, I do not understand what we
want to achieve.
On the GNOME desktop (SLED 11 SP1a2), if you click "Computer" > "Help",
"SLED Documentation (en)" is listed. If you click on it, the HTML
flavor of our docs is shown. You can see something similar on openSUSE.
This, at least, is a start.
Not sure, what needs to be done on KDE, though.

#11: Jan Engelhardt (jengelh) (2009-12-05 13:50:14)
This looks solved to me -- openSUSE 11.2 installs openSUSE-manual_en-
pdf by default, even for a Minimal install chosen in yast.

#12: Karl Eichwalder (keichwa) (2009-12-07 09:50:36) (reply to #11)
openSUSE-manual_en-pdf is just a meta package.

#14: Barry Nichols (barry_nichols) (2009-12-07 12:48:39)
I consider myself to be a regular user and I found the manual pdfs
easily enough.

#17: Karl Eichwalder (keichwa) (2010-01-22 13:55:31) (reply to #16)
Yesterday, I submitted new doc packages for SLE11 SP1. Check on beta3,
whether the implementation is fine.

#20: Karl Eichwalder (keichwa) (2010-02-09 09:51:15) (reply to #17)
HTML of the SLED manuals is visible in yelp.
HTML of the SLES manuals are _not_ visible in KDE helpcenter. I need
info what is required for KDE4.
On SLED, the .desktop files for the PDFs are still missing. I'll try to
create those for yelp. Not sure, how this would work in KDE4.

#22: Lubos Lunak (llunak) (2010-02-26 16:19:09) (reply to #21)
See
http://websvn.kde.org/*checkout*/trunk/KDE/kdebase/runtime/khelpcenter/README.metadata
for details on how to create .desktop files that add new manuals to the
KDE helpcenter (they belong to
/usr/share/kde4/apps/khelpcenter/plugins). E.g. the following is enough
to show openSUSE manuals, but you may consider using more fields (e.g.
X-DOC-Weight to make it appear near the top):
[Desktop Entry] X-DocPath=/usr/share/doc/manual/opensuse-
manuals_en/manual/index.html Name=openSUSE Manuals
It looks to me like none of our documentation integrates with KDE,
while it includes files for GNOME in /usr/share/gnome/help. I can see
this being true at least for opensuse-manuals_en, apparmor-admin_en and
sles-manuals_en. Those all should be fixed. Do you want a bugreport or
saying this here enough?

#23: Karl Eichwalder (keichwa) (2010-03-01 11:04:51) (reply to #22)
Thanks for the info!
If possible I'd rather like to avoid adding special KDE (instead I'd
like to remove all the files that were needed for KDE3).
wikipedia claims the KDE also understands the "rarian" files:
http://en.wikipedia.org/wiki/Rarian
As recommended by Vincent, I now provide those files in
/usr/share/help/ with the .document suffix. They look as follows (is
this good enough for KDE?):
[Document] DocPath=file:///usr/share/doc/manual/opensuse-
manuals_en/manual/index.html DocType=text/html DocLang=en
Icon=document2 Categories=System;Core;Translation;Documentation
Name=openSUSE Security Guide as Documentation (en) Name[en]=openSUSE
Security Guide as Documentation (en) # DocPath= # Icon=document2 X-DOC-
DocumentType=text/html DocIdentifier=com.novell.opensuse-manualsen
DocWeight=0
For the moment let's ignore that there is something wrong with the
Name... I'll try to fix it.
No, there is no need to create a separate bug entry; I'll track the
issue here.

#24: Lubos Lunak (llunak) (2010-03-02 13:38:42) (reply to #23)
I do not see anything in KHelpCenter that'd have a relation to Rarian
or .document files, the wiki page must be wrong and I've removed the
KDE information from there. I assume this is another GNOME thing that
has become "standard" just because they host it as freedesktop.org .
Therefore in practice I consider those files to be GNOME special and as
such I don't see a reason against including also KDE special files.
Since the format is very similar they could be even synced by a script
from the GNOME ones. That also means that this FATE item is not done
yet (SP1 definitely, I don't have recent Factory to check, but I doubt
that's different).

#18: Stephan Kulow (coolo) (2010-02-08 11:21:22)
I still fail to see what's left to do for 11.3

#19: Karl Eichwalder (keichwa) (2010-02-09 09:46:44) (reply to #18)
On 11.3 (and even 11.2 plus updates), it is probably fine.

+ #26: Karl Eichwalder (keichwa) (2010-03-10 15:20:54)
+ If more is wanted, please create dedicated features.



--
openSUSE Feature:
https://features.opensuse.org/306404

< Previous Next >
This Thread
References