1.0 (Mac OS X Mail 10.2 \(3259\))
Tue, 24 Jan 2017 10:45:27 +1030
> On 23 Jan 2017, at 6:40 am, Andrew Parsloe <[log in to unmask]> wrote:
> More generally, when one is trying to use a package for the first time, it can be difficult transforming the rather abstract presentation in the documentation into concrete use.
That’s because when we wrote the documentation there were no “real life” examples :)
> E.g., I have been aware of xtemplate for some time but only recently, having "discovered" the acro package of Clemens Niederberger and seeing the clear presentation of an actual use of xtemplate, does the documentation "make sense". It would be helpful if the reader of the documentation could be pointed toward paradigmatic examples of use of packages or modules. (If not in the package documentation then perhaps in the l3StyleGuide?)
That’s not a bad idea but I do worry about such lists becoming “stale” and/or difficult diplomatically if some people would like to include a package in the list and others not.
I like the idea of adding to l3styleguide as a general “here are a list of paradigmatic examples” with an annotation or two for why they’re included in the list, but I probably don’t have time today to put something together...
> (In fact acro.sty is the most elegantly and clearly presented .sty file I've met. Unfortunately it isn't picked out by the MiKTeX filter with any likely keyword for someone looking for expl3 or xtemplate examples.)
Thanks for pointing it out — I agree, the .sty file is particularly well laid out.