GNOME Bugzilla – Bug 681806
Port to new documentation infrastructure
Last modified: 2012-09-03 19:29:57 UTC
Created attachment 221091 [details] [review] Use-new-documentation-infrastructure Use yelp-tools instead of gnome-doc-utils. https://live.gnome.org/GnomeGoals/NewDocumentationInfrastructure
Review of attachment 221091 [details] [review]: Looks fine to me as a change, before we go ahead with this, can you tell me what is now required for building as a maintainer (i.e. from git) ? Must we install yelp in order to get the appropriate .m4 files implementing YELP_HELP_INIT ? Or is the .m4 included somewhere more general, like in gnome-common ?
Ah, found it in yelp-tools, looks fine to me. A minor annoyance that one has to install itstool first in order to install yelp-tools, but seeing as yelp-tools is just a collection of scripts (no compilation involved), this should not be a problem for us. HOWEVER. There is some kind of problem with the migration approach proposed in https://live.gnome.org/GnomeGoals/NewDocumentationInfrastructure I quote: "IMPORTANT: Do not port to the new system if the application still needs to run under GNOME 2. Yelp 2 does not recognize the new help system." In fact, we maintain Glade 3.8 for the purpose of supporting migration paths from older projects targetting GTK+2. 3.8 is parallel installable with 3.10 and both of them can be installed equally on a GNOME 2 or GNOME 3 desktop (as well as on osx or win32 for that matter). This is not a real issue *yet* because we've removed the UI entry point to show Yelp, because our user manual simply lacks too much content to be worth showing at all. But for developer documentation, we do have fallbacks to show the developer help in a browser when running in an environment without DevHelp. The same should be true for user documentation. So I must ask the question (since we dont really use the user manual enough, unfortunately I just dont know this stuff): o Will the yelp docs generator also generate html which can be published online ? o What will be the expected user experience when trying to view the user manual from a GNOME 2 environment, a win32 or an osx environment ?
> o Will the yelp docs generator also generate html which can > be published online ? yes, as they are today in http://developer.gnome.org/glade/ > o What will be the expected user experience when trying to view > the user manual from a GNOME 2 environment, a win32 or an osx environment As you read, you have to have yelp 3.x installed, so we can point to the url posted before.
Ok thanks for the information on that... please feel free to commit this to master and close the bug.
Comment on attachment 221091 [details] [review] Use-new-documentation-infrastructure commit ecc26f61ede9d5f0d1ec0d986e755c34808130c4