| Summary: | Standardise documentation format in introspection XML | ||
|---|---|---|---|
| Product: | dbus | Reporter: | Philip Withnall <bugzilla> |
| Component: | core | Assignee: | D-Bus Maintainers <dbus> |
| Status: | RESOLVED MOVED | QA Contact: | D-Bus Maintainers <dbus> |
| Severity: | enhancement | ||
| Priority: | medium | CC: | marejde |
| Version: | git master | ||
| Hardware: | All | ||
| OS: | All | ||
| Whiteboard: | |||
| i915 platform: | i915 features: | ||
|
Description
Philip Withnall
2015-02-05 13:48:29 UTC
This would be nice, but I don't see it happening particularly soon. (In reply to Simon McVittie from comment #1) > This would be nice, but I don't see it happening particularly soon. I think all it should take is a bit of discussion (or executive decision) and updating the official guidelines in the documentation (I’m happy to do that). I don’t think we need to port existing modules to use the new standard; but at least get something established so that new modules don’t continue to be fractured. The ‘doc’ namespace seems to be the best contender to me. The other alternative is to punt on specifying an officially recommended documentation format for the XML introspection format, and instead simply defining one for the structured replacement for XML: bug #98006. In that bug, I’m suggesting allowing a{sv} annotations in all places in the introspection data, and specifying documentation as an org.freedesktop.DBus.Introspection2.Documentation annotation with type a{ss}. The a{ss} value should map a locale name (see `man setlocale`, e.g. ‘en_GB’) to a documentation string in that locale. I suspect most documentation will end up being in ‘en_US’. The documentation should be written in Markdown format. Since introspection data is not returned as XML, whitespace is significant, so we no longer have the problem of losing newlines. (In reply to Philip Withnall from comment #0) > • ‘doc’ namespace, http://www.freedesktop.org/dbus/1.0/doc.dtd I get the following error accessing this document: Not Found - The requested URL /dbus/1.0/doc.dtd was not found on this serverers) (In reply to Ralf Habacker from comment #4) > (In reply to Philip Withnall from comment #0) > > > • ‘doc’ namespace, http://www.freedesktop.org/dbus/1.0/doc.dtd > I get the following error accessing this document: Not Found - The requested > URL /dbus/1.0/doc.dtd was not found on this serverers) Yup, as far as I know that DTD has never been defined formally. (In reply to Philip Withnall from comment #5) > (In reply to Ralf Habacker from comment #4) > > (In reply to Philip Withnall from comment #0) > > > > > • ‘doc’ namespace, http://www.freedesktop.org/dbus/1.0/doc.dtd > > I get the following error accessing this document: Not Found - The requested > > URL /dbus/1.0/doc.dtd was not found on this serverers) > > Yup, as far as I know that DTD has never been defined formally. With bug 89011 they are now installed and public. Time to make it also public on the server ? (In reply to Ralf Habacker from comment #6) > With bug 89011 they are now installed and public. Time to make it also > public on the server ? No, Bug #89011 is about the introspection DTD. As far as I know, http://www.freedesktop.org/dbus/1.0/doc.dtd has never existed or been maintained by the D-Bus maintainers; it's a just case of a third party project prematurely assuming that their proposed addition to D-Bus will be accepted (which in fact it wasn't). -- GitLab Migration Automatic Message -- This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/dbus/dbus/issues/120. |
Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.