Em 14 de agosto de 2018, Allin escreveu:
Change of sub-topic: Does anyone have any clever ideas regarding the
formatting of plain-text help for function packages?
At present we have an unholy mixture of styles -- this is
mercilessly exposed by the experimental web business up-thread but
is also apparent on viewing package help within gretl.
Some authors favor very short lines that look kinda silly relative
to the standard width of printed material in gretl (that is,
somewhere between 70 and 80 characters per line). Other authors
write very long lines that have to be word-wrapped. Word-wrapping is
fine in some cases, but it totally mangles lines that have been
typed with a hanging indent (or worse, two nested hanging indents!).
One possible idea would be to insist on markdown in gfn text help,
though I think markdown itself has problems in the line-length
department. I've been contemplating the idea of a post-processor
which would "fix" the help text for a package when it's uploaded to
the server, but the more examples I look at, the more it seems like
this would be an advanced AI project!
Another possibility would be to require that all packages have PDF
documentation, though that would both raise the bar for package
contribution and spell the end of standalone gfn files.
Any better/different ideas?
It's not a better/different idea, but I think Markdown is a great way
to write texts. I'm using a lot of it in my R scripts (via RMarkdown)
and I'm very satisfied with the results.