Hi, On Sun, Sep 13, 2015 at 02:36:47PM -0600, Jonathan Corbet wrote: > On Mon, 7 Sep 2015 17:01:59 -0300 > Danilo Cesar Lemes de Paula <danilo.cesar@xxxxxxxxxxxxxxx> wrote: > > The "highlight" code is very sensible to the order of the hash keys, > > but the order of the keys cannot be predicted. It generates > > faulty DocBook entries like: > > - @<function>device_for_each_child</function> > > > > Sorting the result is not enough some times (as it's deterministic but > > we can't control it). > > We should use an array for that job, so we can guarantee that the order > > of the regex execution on dohighlight is correct. > OK, I've spent a bunch of time with this, comparing the results before > and after. The output you mention is clearly wrong, but there might be > room to differ over what the root cause is. > > That output is caused by @device_for_each_child() in the comments. This > happens for a few other functions as well, and I think it's wrong. @ is > used to indicate parameters (or structure fields); I'm not sure why > people are using it for functions that are *not* one of the above. > Formatting the function names as a parameter doesn't seem right either. Shouldn't kernel-doc print a warning for syntactic mistakes like this rather than silently accomodating to it in whatever way? As to the usage of markdown in general, there's documentation coming up for vga_switcheroo which makes use of that so I'd love to see it merged: https://github.com/l1k/linux/commit/d1476d748b5f1adf5bffe8e0a8bafad1e879d22f https://github.com/l1k/linux/commit/11c55ae65788162970d8fa23cd1fd2518af55d34 The large set of dependencies pulled in on Fedora is likely to be blamed on the RedHat packaging being notoriously coarse-grained. By comparison, Debian is extremely fine-grained, kind of the opposite extreme, and therefore has comparatively few prerequisites: https://packages.debian.org/jessie/pandoc I do agree however that alternative tools with fewer dependencies should be supported and it would be great if the markdown patches were amended to that end. Best regards, Lukas -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
