6:37 a.m.
Hi,
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.
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.
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?
Thanks for reading this long post,
Sven
3:29 p.m.
m 21 de agosto de 2018, Sven escreveu:
(...)
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.
I totally agree. Additionally, IMHO, we could get more visibility if
we put a "contributed functions" entry on the side menu of Gretl's
home page.
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.
Just one "newbie" thought: I can't remember why we have zip as a
function format in addition to the gfn.
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.
I really think markdown offers the best solution when we think about
the trade-off between "easy of use" and "flexibility". But we
can't
forget we need to choose the markdown implementation we will follow
(CommonMark, GitHub Flavored Markdown, etc.)
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 think we can use something we are already familiar with (but I'm not
sure about possible indentation issues):
<hansl>
markdown
# your code
end markdown
</hansl>
A more simple and direct alternative is just write a "help.md" file
inside the function folder.
Thanks for reading this long post,
No worries. It's a nice post :-)
Best,
Henrique Andrade
3:46 p.m.
Am 21.08.2018 um 17:29 schrieb Henrique Andrade:
m 21 de agosto de 2018, Sven escreveu:
(...)
> 2: Another already mentioned gap are the zip packages without pdf file.
Just one "newbie" thought: I can't remember why we have zip as a
function format in addition to the gfn.
gfn is a single-file text format (being
XML). If a package author wants
to add other arbitrary files (including, but not only, PDF files) that
are needed or useful for the package, it has to be the zipped format.
Inside the zip thing there will still be a gfn file.
> 3: Then the "markdown" business for plain --or not so
plain-- text help
> docs.
I really think markdown offers the best solution when we think about
the trade-off between "easy of use" and "flexibility". But we
can't
forget we need to choose the markdown implementation we will follow
(CommonMark, GitHub Flavored Markdown, etc.)
Exactly -- what's your
recommendation or opinion?
I think we can use something we are already familiar with (but
I'm not sure about possible indentation issues):
<hansl>
markdown
# your code
end markdown
</hansl>
Well, we're talking about the help text in general, not hansl
code. I
see no real reason to use a hansl-style markdown - end markdown block here.
A more simple and direct alternative is just write a
"help.md" file
inside the function folder.
For a plain-text help everything has to be inside the
single gfn file,
additional files are not possible.
cheers,
sven
8:47 p.m.
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
7:14 a.m.
Am 21.08.2018 um 22:47 schrieb Allin Cottrell:
I'm not against use of markdown -- definitely worth considering -- but
a few other things (not necessarily mutually exclusive) are also worth
considering.
Yes, not substitutes but could be complementary.
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).
Good idea,
yes.
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 ;-)
What do you mean with "presented by gretl"? Where does gretl present
information on the gfns, apart from outputting the help text verbatim?
thanks,
svne
2:41 p.m.
On Wed, 22 Aug 2018, Sven Schreiber wrote:
Am 21.08.2018 um 22:47 schrieb Allin Cottrell:
>
> 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 ;-)
>
What do you mean with "presented by gretl"? Where does gretl present
information on the gfns, apart from outputting the help text verbatim?
If you select a package in the function-package viewer window,
right-click and choose Info (or click the Info button in the window's
toolbar), gretl opens a window showing what it knows about the
function: where it's located in the filesystem; its name, version and
date; author's name and email; required gretl version; dataset
requirement; and brief description -- this is all gleaned from the gfn
metadata. Then the supplied help text is appended verbatim.
In the case of packages that have PDF help, gretl prints the names of
the public functions then a link to the PDF file.
Related thought: a standard way of documenting individual functions in
source code is via regimented comments -- the content of such comments
can be extracted and pretty-printed by a suitable module, producing
output such as
https://developer.gnome.org/gtk2/2.24/GtkDialog.html
It might be worth devising a suitable stuctured comment style for
hansl functions. For example (just off the top of my head):
function scalar foo (<args>)
## COMMENT
## Text goes here.
## More text if wanted.
## EXAMPLE
## open somedata
## y = foo(x)
where "## COMMENT" (directly following the function signature) opens a
block of lines starting with two hash marks, to be interpreted as
commentary on the function's purpose, and "## EXAMPLE" starts a
similar block showing an example call. In each case the special block
is taken to end when we encounter a line that does not start with two
hash marks.
Line-breaks are often an issue, but in the ## COMMENT section we could
employ the convention that lines are to be run into a single paragraph
unless an empty line is inserted:
## COMMENT
## Para 1.
## Still para 1.
##
## Para 2.
If this mechanism were combined with auto-generation of the function's
signature from the gfn we could have a nicely set-out block of
signature
comments
example
for each public function. And in that case the actual "help text" in
the gfn file could be confined to a general account of the purpose of
the package, how it relates to the econometric literature and so on.
That help text could use markdown, I guess.
Allin
5:28 p.m.
Am 22.08.2018 um 16:41 schrieb Allin Cottrell:
On Wed, 22 Aug 2018, Sven Schreiber wrote:
> Am 21.08.2018 um 22:47 schrieb Allin Cottrell:
>>
>> 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 ;-)
>>
> What do you mean with "presented by gretl"? Where does gretl present
> information on the gfns, apart from outputting the help text verbatim?
If you select a package in the function-package viewer window,
right-click and ...
Sorry, that was a misunderstanding, I knew that. I was still focussing
on the help text itself. But yes it's a good idea to output the
structured information on the function signatures etc.
Related thought: a standard way of documenting individual functions in
source code is via regimented comments -- the content of such comments
can be extracted and pretty-printed by a suitable module,
What comes immediately to
my mind are the so-called 'docstrings' in
Python, which are (triple-quoted, I believe) strings just below the
function signature. One of the nice things is that in some consoles you
can directly access those help strings - in ipython for example by doing
'myfunc?'. If at some point in the future in gretl (in the console) you
could directly access those strings also for loaded hansl functions that
would of course be great.
But in a sense it's a digression I believe. Earlier on the agenda (and
in this thread) is the issue of help texts in the packages and how to
format them, irrespective of the functions themselves.
thanks,
sven
1:43 p.m.
Am 21.08.2018 um 22:47 schrieb Allin Cottrell:
On Tue, 21 Aug 2018, Sven Schreiber wrote:
> 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.
Actually it seems the list (of zips without pdf) is a little longer than
I thought at first. Still nothing to be afraid of, but here it is, for
the record:
- CanovaHansen (Ignacio et al.)
- dhurdle (Jack)
- DIF_panelcoint (Francesca/Stefano)
- DST_test (Marcin)
- GHegy (Ignacio)
- gregory_hansen (Artur)
- MGARCH (Jack)
- staticfactor (Jack and myself, whoops)
- Threshold_Panel (Artur)
cheers,
sven
3:25 p.m.
Am 24.08.2018 um 15:43 schrieb Sven Schreiber:
Am 21.08.2018 um 22:47 schrieb Allin Cottrell:
> On Tue, 21 Aug 2018, Sven Schreiber wrote:
>
>> 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.
Actually it seems the list (of zips without pdf) is a little longer
than I thought at first. Still nothing to be afraid of, but here it
is, for the record:
- CanovaHansen (Ignacio et al.)
- dhurdle (Jack)
- DIF_panelcoint (Francesca/Stefano)
- DST_test (Marcin)
- GHegy (Ignacio)
- gregory_hansen (Artur)
- MGARCH (Jack)
- staticfactor (Jack and myself, whoops)
- Threshold_Panel (Artur)
Thanks for this overview, Sven. It's on my todo-list.
Best,
Artur
2622
days inactive
2628
days old
8 comments
4 participants
participants (4)
-
Allin Cottrell -
Artur T. -
Henrique Andrade -
Sven Schreiber