|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 02/02/2015 05:51 PM, Philip Withnall wrote: > On Mon, 2015-02-02 at 07:55 -0800, Jasper St. Pierre wrote: >> >> On Feb 2, 2015 6:37 AM, "Philip Withnall" <philip tecnocode co uk> >> wrote: >>> >>> On Mon, 2015-02-02 at 12:19 +0100, Olav Vitters wrote: >>>> On Mon, Feb 02, 2015 at 08:05:00AM +0000, Philip Withnall wrote: >>>>> It was suggested that I send the presentation to DDL, since it >> might be >>>>> of general interest. I haven’t modified it from the hackfest >> version, so >>>>> please let me know if you have any questions. >>>> >>>> Can we assume that most still needs to be actioned? Also >> interested what >>>> discussions there were during the hackfest to improving this. E.g. >>>> Should we maybe reach out to our advisory board? Some things >> mentioned >>>> lack of documentation. So with DX hackfest and documentation at >> same >>>> time I also wonder if there were any possibilities to improve >> this. >>> >>> Some of the items need actioning via bugs, which I will sort out. >> Some >>> of them have already been fixed (either as part of the client work >> by >>> Collabora, or by others in the time since). Some of them are >> unfixable, >>> and can only be used as general guidelines for trying to avoid such >>> problems in future (e.g. in new API designs). >>> >>> What do you mean by reaching out to the advisory board? Reaching out >> for >>> further feedback from them as downstreams, or reaching out for >> resources >>> to fix such issues? I think the former would be interesting. I’m not >>> sure the latter is worth their time, since it’s a very loosely >> defined >>> goal. >>> >>> There were some DX–documentation discussions, although I wasn’t >> involved >>> in all of them so I can’t report fully. One interesting discussion >> came >>> up with a set of requirements for any replacement for gtk-doc: >>> 1. Do not want to write XML in documentation comments. Too painful, >> and >>> a steep learning curve. >>> 2. No version control program (but wikis’ version control is fine). >> Too >>> much of a barrier for contribution. >>> 3. No waiting for review of documentation changes — post-hoc gives >> a >>> much lower barrier to contribution instead. >>> 4. Instant gratification: documentation changes should be visible >>> instantly, rather than waiting 6 months for a GNOME release >> before >>> the docs hit developer.gnome.org. >>> 5. Documents need to be available offline in Devhelp. >>> 6. Devhelp needs to give you documentation for the version of the >>> library you’re using (e.g. in JHBuild), not the version >> installed on >>> your system, which is invariably outdated. >>> 7. Automatically generate documentation from annotations as much as >>> possible (e.g. eliminate ‘Free return value with g_free()’ in >> favour >>> of (transfer full)). >>> 8. Topic-based help which can be reorganised dynamically; eliminate >>> in-order Docbook indexes. Basically the Mallard approach for >>> reference documentation. >>> 9. Don’t put big code examples in C comments; move them to separate >> C >>> files instead, which can be compiled stand-alone. Have a way of >>> limiting what gets rendered in the docs, plus a link to the full >>> source. >>> 10. Don’t parse C with regexps; use documentation from GIR files, >> and >>> allow g-ir-scanner to do the C parsing legwork. >> >> I'm confused. You want both a wiki, and docs embedded in comments? >> What are you imagining here? > > Sorry, I should have explained that more clearly. > > Documentation is generated from C comments as at the moment, > reformatted, uploaded to developer.gnome.org, and then some kind of > online interface can be used to edit the documentation (and possibly add > comments to it) with instant gratification. That’s what the first few > points are about. This was proposed already for GSOC. In a nutshell the idea was that gtk-doc would a markdown editor with extra metadata into the generated html. When editing this would submt patches to bugzilla (as this is our code-review tool). The infrastructure team was against tools submiitting to bugzilla. We could probably also push to special doc-review branches on git. While this sounds all doable, it unfortunately get more complicated. We'd need to show that a doc 'unit' already has pending patches so that new edits won't clash, then engine would need to be able to somehow rebase them one new doc-builds, ... Stefan > > > There are no requirements covering how these online edits would be fed > back into the C comments, but presumably that would happen somehow. The > fact that there are no requirements means nobody in the hackfest > discussion had strong feelings about how it should be done. > > Philip > > > _______________________________________________ > desktop-devel-list mailing list > desktop-devel-list gnome org > https://mail.gnome.org/mailman/listinfo/desktop-devel-list -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iEYEARECAAYFAlTRQ7IACgkQITDA+qr9gcyTdwCfRUKg5Acv7AhtvMlMjNnNDHfE llYAnROqAGAF20ZWp/36dNeFhrl5PanW =yG9M -----END PGP SIGNATURE----- |