Re: [Gretl-devel] Standards for function package help
On Tue, 21 Aug 2018, Sven Schreiber wrote:
let me start a new thread here on the devel list about the function
package
help business.
First, thanks to Allin the situation is already much improved. My hope is
that the better online accessibility also leads to higher visibility among
users.
Then there are two or three pending questions I think.
1: Addons are not covered in the list. I think that's perfectly fine, but for
outsiders the difference between contributed packages and addons is not so
clear. And now the core gretl docs as well as regular package docs are
online, but the addons docs are not (or very hidden).
Two suggestions here: Add a remark at the top of the SHOW_FUNCS output that
addons are elsewhere. And secondly perhaps add the pdf help files of the
addons to the same place where
http://sourceforge.net/projects/gretl/files/manual/ links to. Because this
latter link is also on the homepage under http://gretl.sourceforge.net/#man.
Agreed. I have some ideas on how the doc for the addons could be
made more visible and I'll try experimenting.
2: Another already mentioned gap are the zip packages without pdf
file. No
immediate action is necessary (Jack has already said he wants to amend the
dhurdle.zip package), but my proposal would be to make a pdf file mandatory
for zip packages.
Again, agree. But no great rush.
3: Then the "markdown" business for plain --or not so
plain-- text help docs.
(For the beginning of the discussion see the 'New "frontier" package
Gretl-users Digest, Vol 138, Issue 14' thread on the users list.) I still
think it's a good idea. The line-length problem just seemed to be a problem
of a faulty implementation. I wouldn't make the use of markdown mandatory to
keep the entry bar low, but we could encourage it.
My first question is whether we agree on that?
The second question is: I guess package authors should use an indicator tag
in their help text if they are indeed using markdown? Simply "<markdown> ...
</markdown>", or how would that work? Also, maybe we only want to support or
encourage the use of a subset of markdown?
I'm not against use of markdown -- definitely worth considering --
but a few other things (not necessarily mutually exclusive) are also
worth considering.
For example, a gfn file contains structured information on all the
public functions (private ones too, but that's less relevant). So we
could easily arrange that the online "doc" for a package includes an
auto-generated (and so automatically up-to-date and complete)
account of the syntax of the public functions, just as it includes
auto-generated info on author, version, etc. (which is, for
historical reasons, redundantly duplicated in the help text in quite
a few cases).
Any gfn-derived information presented by gretl itself can easily be
made "nicely formatted" -- at least if you think the help for the
built-in functions is nicely formatted ;-)
Allin