...
 
Commits (382)
This diff is collapsed.
This diff is collapsed.
How to contribute to Devhelp
============================
Devhelp is hosted on the GNOME GitLab instance, you can fork the repository and
then do a merge request:
https://gitlab.gnome.org/GNOME/devhelp
Read the following wiki page to know the conventions for the commit messages:
https://wiki.gnome.org/Git/CommitMessages
C code conventions
------------------
Devhelp follows the Linux kernel coding style, with some exceptions:
- Indentation: 8 spaces, not tabs.
- One space before *each* opening parenthesis.
- Multi-line comments must be like this:
/* First line.
* Second line.
*/
GObject classes must not be created with a G_DECLARE macro, it causes more
problems than it solves:
https://blogs.gnome.org/swilmet/2015/10/10/changing-quickly-between-a-final-and-derivable-gobject-class/
g_auto macros are not used, because:
1. It makes debugging more difficult in case of a memory handling problem.
2. It breaks the uniformity of memory handling in C. Uniformity is an important
principle for programming language design, as explained in the book
“The Psychology of Computer Programming”:
https://www.amazon.com/Psychology-Computer-Programming-Silver-Anniversary/dp/0932633420/
3. The developer needs to be very careful when using g_auto in certain
circumstances:
https://blog.fishsoup.net/2015/11/05/attributecleanup-mixed-declarations-and-code-and-goto/
See also:
https://developer.gnome.org/programming-guidelines/unstable/
Flatpak
-------
The Devhelp maintainers maintain both the nightly and the stable versions of
the Devhelp Flatpak.
The nightly version is in flatpak/ and the gnome-apps-nightly module:
https://gitlab.gnome.org/GNOME/gnome-apps-nightly
The stable version is on Flathub:
https://github.com/flathub/org.gnome.Devhelp
SUBDIRS = data plugins po help src unit-tests docs
AM_DISTCHECK_CONFIGURE_FLAGS = \
--enable-gtk-doc \
--enable-introspection \
--enable-appstream-util
EXTRA_DIST = devhelp.doap
MAINTAINERCLEANFILES = \
$(GITIGNORE_MAINTAINERCLEANFILES_TOPLEVEL) \
$(GITIGNORE_MAINTAINERCLEANFILES_MAKEFILE_IN) \
$(GITIGNORE_MAINTAINERCLEANFILES_M4_GETTEXT) \
$(GITIGNORE_MAINTAINERCLEANFILES_M4_LIBTOOL) \
gtk-doc.make \
py-compile
-include $(top_srcdir)/git.mk
This diff is collapsed.
News in 3.30.1, 2018-10-24
--------------------------
* Build: requires Meson >= 0.47.
* Translation updates.
News in 3.30.0, 2018-07-16
--------------------------
* A few small improvements.
* Translation updates.
News in 3.29.3, 2018-06-17
--------------------------
* Devhelp has moved to the GNOME GitLab instance. The bugzilla tickets have not
yet been migrated to the GitLab issues, so before filing a new issue on
GitLab, please search the bugzilla first. All links are available as usual
on:
https://wiki.gnome.org/Apps/Devhelp
* Finally write a HACKING file.
* Do not show a GtkInfoBar on error, use the WebKitWebView default
implementation to simplify the code.
* Code refactorings: from DhWindow extract DhNotebook, DhSearchBar and
bind_sidebar_and_notebook() function, and delegate more work to DhWebView.
* Make the following classes re-usable and move them to the libdevhelp:
DhWebView, DhTab, DhTabLabel, DhNotebook and DhSearchBar.
And move dh_window_bind_sidebar_and_notebook() to the libdevhelp.
* Flatpak: run Amtk and Devhelp unit tests after building those modules.
* Application icons: rename filenames to org.gnome.Devhelp.*, to simplify the
Flatpak manifest.
* Build system: fix the remaining places where the libdevhelp API/major version
was hardcoded, use the variable instead, to easily bump it in the future.
* Other small improvements.
* Translation updates.
News in 3.29.2, 2018-05-21
--------------------------
* A new, more flexible book management architecture in the libdevhelp:
- DhBookManager is now completely empty and entirely deprecated, the minimum
amount of API is kept to not break Anjuta. It has been replaced by a more
flexible infrastructure: DhProfile, DhSettings and DhBookList. If an
application uses only the default libdevhelp widgets it will still work fine
– even if the code of the application is not adapted – because in that case
it will use the default DhProfile, which contains the same content as how
DhBookManager was implemented.
- Whether a DhBook is enabled/selected is now decoupled from DhBook:
dh_book_get_enabled() and dh_book_set_enabled() have been removed, as well
as the DhBook::enabled and DhBook::disabled signals. For a book to be
enabled it now needs to be part of a DhBookList, which is more flexible
because there can be several different DhBookLists in parallel.
- Allow custom search paths to load DhBooks, with DhBookListDirectory.
* Port other Devhelp classes to DhProfile and DhBookList.
* Listen to external changes to the "books-disabled" GSettings key.
* Some code cleanup and minor bug fixes.
* Flatpak: convert manifest to YAML.
* Translation updates.
News in 3.29.1, 2018-04-15
--------------------------
* Switch build system from Autotools to Meson (and remove Autotools).
* Update the license from GPLv2+ to GPLv3+.
* Clear separation between the library and the app: move library to its own
directory (still in the same git repo), split some source files in two,
correctly handle GSettings in the library, and in the app use only really
public libdevhelp APIs.
* Add a profile infrastructure in the library, for example to have a generic
profile and a GNOME profile in the future.
* Overhaul preferences dialog implementation.
* Use the Amtk library to create the menus and the GtkShortcutsWindow. It
permits to avoid information duplication, and will permit to provide a
higher-level libdevhelp API.
* A few other small improvements.
* Translation updates.
News in 3.28.1, 2018-04-08
--------------------------
* AppData: update screenshots.
......
......@@ -5,12 +5,18 @@ The Devhelp web page:
https://wiki.gnome.org/Apps/Devhelp
How to contribute
-----------------
See the HACKING file.
Dependencies
------------
- glib >= 2.40
- glib >= 2.56
- gtk+ >= 3.22
- webkit2gtk-4.0 >= 2.19.2
- webkit2gtk-4.0 >= 2.20
- Amtk >= 5.0 - https://wiki.gnome.org/Projects/Amtk
- gsettings-desktop-schemas
Description
......@@ -67,23 +73,26 @@ documentation. You can read more about that specification here:
The list of locations searched for devhelp books is:
$XDG_DATA_HOME/devhelp/books
e.g. /home/ross/.local/share/devhelp/books/glib-2.0/glib-2.0.devhelp2
e.g. ~/.local/share/devhelp/books/glib/glib.devhelp2
or with Flatpak: ~/.var/app/org.gnome.Devhelp/data/devhelp/books/glib/glib.devhelp2
$XDG_DATA_HOME/gtk-doc/html
e.g. /home/ross/.local/share/gtk-doc/html/glib-2.0/glib-2.0.devhelp2
e.g. ~/.local/share/gtk-doc/html/glib/glib.devhelp2
or with Flatpak: ~/.var/app/org.gnome.Devhelp/data/gtk-doc/html/glib/glib.devhelp2
$XDG_DATA_DIRS/devhelp/books
e.g. /usr/local/share/devhelp/books/glib-2.0/glib-2.0.devhelp2
e.g. /usr/share/devhelp/books/glib/glib.devhelp2
$XDG_DATA_DIRS/gtk-doc/html
e.g. /usr/local/share/gtk-doc/html/glib-2.0/glib-2.0.devhelp2
e.g. /usr/share/gtk-doc/html/glib/glib.devhelp2
Note that the two latter consist of :-separated lists of directories to
look for. Those environment variables are normally set up by the
desktop environment or distribution.
Note that the name of the directory the *.devhelp2 file is in and the
name of the *.devhelp2 file (minus the extension) must match.
Note that the name of the directory the *.devhelp2 file is in and the name of
the *.devhelp2 file (minus the extension) must match ("glib" in the above
examples).
The first version of the index file format (with the *.devhelp file
extension) is deprecated and its support will probably be removed in a
......
Possible things to do in Devhelp
================================
Normally all the codebase is in a good state, except DhAssistant because I
don't use it (and I think it's sometimes broken).
Some stuff that can be done:
Improve DhBookList API
----------------------
Make it easier to create a custom DhBookList. Maybe expose publicly
DhBookListSimple and be able to subclass it.
Have man-pages for the lib C
----------------------------
https://bugzilla.gnome.org/show_bug.cgi?id=616509#c6
Create a software product line
------------------------------
By moving almost all the code to the libdevhelp (so the software product line
is implemented by developing a library, using classic OOP design patterns).
Same idea as Tepl, but applied to a smaller codebase. See:
https://developer.gnome.org/tepl/unstable/intro.html
https://www.amazon.com/Feature-Oriented-Software-Product-Lines-Implementation/dp/3642375200/
In Devhelp it's almost done. What remains is DhApplicationWindow, DhApplication
(see how it is done in Tepl) and a toolkit to build a preferences dialog (my
plan was to at least factor out a DhBookChooser widget from DhPreferences).
Then with the software product line, different API browser products can be
created: a generic one (same as current Devhelp), one specific for GNOME, etc.
See also the roadmap on the wiki.
Improve DhSettings
------------------
For the software product line, one thing that is not present in Tepl (so I
needed to do the first iteration in Devhelp), is DhSettings to handle the
GSettings in a library. The goal is of course to have the minimum amount of
code or work to do in the applications.
But I'm not entirely satisfied by the current DhSettings. But to make it better
it would require lots of boilerplate code, so I was maybe thinking about a code
generation tool that reads the GSettings XML schema and creates a GObject class
with some properties and functions for each key. Then DhSettings would come on
top of that generated class (either as a subclass or using it by composition)
to add more specific functions like is_book_enabled(), set_book_enabled(), etc.
The code generation tool would do something along those lines:
- Add a property of type GVariant for each GSettings key.
- Add getters/setters for the GVariant properties (bonus if for simple types
like integers, strings, booleans, the getters/setters use the appropriate
GLib type, not GVariant. Or find a way to make it convenient to use GVariant
to get/set the properties).
- Add bind_to_key() functions, to bind a GVariant property to its corresponding
GSettings key.
- For each key, add another property of type boolean to know whether the
GVariant property has been bound to the GSettings key. Same name as the
GVariant property, but with the -bound suffix.
- Add one bind() wrapper function with an API like g_settings_bind(), but calls
g_object_bind_property() if -bound property is FALSE, and calls
g_settings_bind() if -bound property is TRUE, to take advantage of the
writability of the GSettings key.
- If more flexibility is needed, add getters to get the GSettings objects,
those can be used for the keys where the -bound property is TRUE.
This diff is collapsed.
TODO Devhelp attic
==================
Triage the files, remove what is no longer needed, and better document what is
still useful (if it's still useful it can be moved to another directory).
For describing the index file format, a *.rng file would be better. The
devhelp-1.dtd seems to describe the index file format version 1, which is
deprecated. What are the other *.dtd files?
<?xml version ="1.0" ?>
<!ELEMENT book (chapters,functions?)>
<!ATTLIST book title CDATA #REQUIRED
name CDATA #REQUIRED
base CDATA #IMPLIED
version CDATA #IMPLIED
link CDATA #REQUIRED
author CDATA #IMPLIED>
<!ELEMENT chapters (sub*,chapter*)>
<!ELEMENT chapter (sub*,chapter*)>
<!ATTLIST chapter name CDATA #REQUIRED
link CDATA #REQUIRED>
<!ELEMENT sub (sub*,chapter*)>
<!ATTLIST sub name CDATA #REQUIRED
link CDATA #REQUIRED>
<!ELEMENT functions (function+)>
<!ELEMENT function EMPTY>
<!ATTLIST function name CDATA #REQUIRED
link CDATA #REQUIRED>
<?xml version ="1.0" ?>
<!ELEMENT contents (section+)>
<!ELEMENT section (section*)>
<!ATTLIST section title CDATA #REQUIRED
url CDATA #REQUIRED>
<?xml version ="1.0" ?>
<!ELEMENT keywords (keyword+)>
<!ELEMENT keyword EMPTY>
<!ATTLIST keyword name CDATA #REQUIRED
url CDATA #REQUIRED>
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
These scripts are not maintained by the Devhelp maintainer and suggestions and
comments should be sent directly to the script author.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
[D-BUS Service]
Name=org.gnome.Devhelp
Exec=@bindir@/devhelp --gapplication-service
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.