[Bug 147668] Re: No way to browse applications' manuals
1. Blindly listing documents by application name without a coherent categorisation means that regular users are just going to stop reading the help and go somewhere else. Matthew, please note that the Advanced Topics document starts with this phrase: The Ubuntu help system contains a lot of documentation, not all of which you see in the table of contents. You can, of course, use the search feature, but as well as you allow to browse man and info pages by category (Advance Topics-Terminal Commands References // Advanced Topics-GNU Info Pages), I think we should allow to browse XML/Docbook manuals by category too. Just a real case example: the Italian GNOME team provides guidelines for Italian translation. I wrote those using XML/Docbook, packed inside a tgz that works like the gnome-user-docs source package: run configure/make/make install and read in Yelp. It's an external and additional document, of course, and it's useful only for Italian translators: there is no interest to merge it in the structure of Ubuntu documentation system. This to explain that the GNOME help system can be used to provide more then application manual. So, IMHO, hiding the index for XML/Docbook documents is a bad idea: it should be available near the man in info index. You can of course use a different default approach to help users to browse, but any documentation system needs an index. 2. Quite a lot of the documents listed in the standard yelp indexes are totally irrelevant to the vast majority of desktop users and confuse them rather than assist them (e.g. GNOME Documentation XSLT Manual). This is a different issue, not related to provide an index for XML/Docbook. Could be solved in deb package build, splitting doc stuff. However, note also that XSTL manual is listed under Other documents category, the proper category for other stuff: if you are browsing here, you should know that you can find odd stuff :-) And just to note that both the major Gnome manuals (accessibility guide and user guide) are incorporated into the layout. The Accessibility guide now has its own entry. system-admin-guide guide seems still out to me. As well as manuals from the new gnome-devel-docs module. maybe this is not yet included in Ubuntu, but it provide useful sfuff: an overview of GNOME Desktop for developers, the HIG, the style guide for manuals and a simple guide to integrate non-GNOME apps in GNOME Desktop (application menu, mime type, icons...) If there are specific pages which you believe should be included in the current setup, and aren't, please file a bug on ubuntu-docs. I could like something like the attached HTML for Advance Topics page (note the All Installed Manuals section, come from my previous considerations); links should open related pages on standard gutsy system, except stuff from gnome-devel-docs (platform-overview and hig- book). But it's too late for gutsy, so I'll propose it in the next 6 months. ** Attachment added: My personal view of Advanced Topics page http://launchpadlibrarian.net/10048334/advanced-topics.html -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
Re: [Bug 147668] Re: No way to browse applications' manuals
Hi, On 16/10/2007, Luca Ferretti [EMAIL PROTECTED] wrote: Just a real case example: the Italian GNOME team provides guidelines for Italian translation. I wrote those using XML/Docbook, packed inside a tgz that works like the gnome-user-docs source package: run configure/make/make install and read in Yelp. It's an external and additional document, of course, and it's useful only for Italian translators: there is no interest to merge it in the structure of Ubuntu documentation system. This to explain that the GNOME help system can be used to provide more then application manual. That's fine, and is no doubt a good resource, but it's not relevant to Ubuntu desktop users (which is what we use yelp for). There are any number of ways that you can allow people to view that, such as providing a copy of the document on the internet, html files viewed on a local system, or even docbook xml viewable by calling yelp from the command line, if you really want to use docbook as your final format. But it certainly shouldn't be part of the help system, for the reasons I've given. 2. Quite a lot of the documents listed in the standard yelp indexes are totally irrelevant to the vast majority of desktop users and confuse them rather than assist them (e.g. GNOME Documentation XSLT Manual). This is a different issue, not related to provide an index for XML/Docbook. I don't see how: I understood your original argument to be for all the upstream categories to be included. Now you appear to be arguing for us to include just one link in the help structure to a complete list of all documents which have an omf file installed on the system, unless I've misunderstood. I still disagree with that, and I think the arguments in my previous comment still apply. And just to note that both the major Gnome manuals (accessibility guide and user guide) are incorporated into the layout. The Accessibility guide now has its own entry. system-admin-guide guide seems still out to me. Yes, it doesn't contain much useful material for our purposes. As well as manuals from the new gnome-devel-docs module. maybe this is not yet included in Ubuntu, but it provide useful sfuff: an overview of GNOME Desktop for developers, the HIG, the style guide for manuals and a simple guide to integrate non-GNOME apps in GNOME Desktop (application menu, mime type, icons...) Currently we have a section for development material - the programming article - important documents might be included in that. For myself, I think that including developer documents is not part of the function of a desktop help system, and is harmful to the experience of ordinary users. Information on Ubuntu development is found in a single place at the moment - https://wiki.ubuntu.com/UbuntuDevelopment and I think that's appropriate. I could like something like the attached HTML for Advance Topics page (note the All Installed Manuals section, come from my previous considerations); links should open related pages on standard gutsy system, except stuff from gnome-devel-docs (platform-overview and hig- book). But it's too late for gutsy, so I'll propose it in the next 6 months. Right, I'm not convinced yet but feel free to raise it on the mailing list if you want. -- Matthew East http://www.mdke.org gnupg pub 1024D/0E6B06FF -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
[Bug 147668] Re: No way to browse applications' manuals
you want to use devhelp not yelp for programming documentation -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
Re: [Bug 147668] Re: No way to browse applications' manuals
On 07/10/2007, Jan Claeys [EMAIL PROTECTED] wrote: I think hiding installed documentation is definitely *not* a good idea. You're entitled to your opinion, but we've discussed this in detail over several release cycles with plenty of research. Have a read of https://wiki.ubuntu.com/HelpfulHelp which is probably the best analysis of the help system. Two of the key points are: 1. Blindly listing documents by application name without a coherent categorisation means that regular users are just going to stop reading the help and go somewhere else. 2. Quite a lot of the documents listed in the standard yelp indexes are totally irrelevant to the vast majority of desktop users and confuse them rather than assist them (e.g. GNOME Documentation XSLT Manual). E.g., where have the Python documentation tutorials gone? I thought Ubuntu wanted to promote python programming/scripting? Funnily enough that's one of the categories which is still present: Advanced Topics - Writing your own programs. Those links are broken in the current yelp, although that's another story / bug. -- Matthew East http://www.mdke.org gnupg pub 1024D/0E6B06FF -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
[Bug 147668] Re: No way to browse applications' manuals
I think hiding installed documentation is definitely *not* a good idea. E.g., where have the Python documentation tutorials gone? I thought Ubuntu wanted to promote python programming/scripting? -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
[Bug 147668] Re: No way to browse applications' manuals
+1 for me ** Changed in: yelp (Ubuntu) Status: New = Confirmed -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
[Bug 147668] Re: No way to browse applications' manuals
Matthew, that's due to the Ubuntu layout patch, could you have a look? ** Changed in: yelp (Ubuntu) Importance: Undecided = Low Assignee: (unassigned) = Ubuntu Desktop Bugs (desktop-bugs) Status: Confirmed = Triaged Target: None = ubuntu-7.10-rc -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
[Bug 147668] Re: No way to browse applications' manuals
Thanks for the report. This is an intentional result of our customisations to Yelp, which have been the subject of substantial discussion throughout the last two or three release cycles in the documentation team so for now I'm closing this bug as WONTFIX. The topics currently available should cover most subjects relevant to the desktop user, and inside each topic it should be possible to browser to relevant manuals (and relevant index pages from upstream). The idea is to enable Ubuntu-created documents and upstream material to be merged into the structure rather than separate. Naturally, all the installed manuals are available from the search function as usual (which is where most users actually start). If there are specific pages which you believe should be included in the current setup, and aren't, please file a bug on ubuntu-docs. ** Changed in: yelp (Ubuntu) Status: Triaged = Won't Fix -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
[Bug 147668] Re: No way to browse applications' manuals
the manpages are accessible from the advanced topic left column item which is easy enough to use -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
[Bug 147668] Re: No way to browse applications' manuals
And just to note that both the major Gnome manuals (accessibility guide and user guide) are incorporated into the layout. The Accessibility guide now has its own entry. -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
[Bug 147668] Re: No way to browse applications' manuals
** Attachment added: The Yelp topic page as in upstream, useful to list/browse all installed manuals/guides/man pages/info pages/... http://launchpadlibrarian.net/9620585/original-yelp-topic-page.png -- No way to browse applications' manuals https://bugs.launchpad.net/bugs/147668 You received this bug notification because you are a member of Ubuntu Bugs, which is the bug contact for Ubuntu. -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs
