Add Documentation for Recipe Authors #983

Closed
zwass opened this Issue Dec 9, 2012 · 9 comments

Comments

Projects
None yet
3 participants
Contributor

zwass commented Dec 9, 2012

There's a bit of documentation in the info file, but it's hard to tell what everything does in recipes. Real documentation on this would probably do wonders for acquiring new, correct recipes.

As a stopgap, can someone just point me to the code that handles processing recipe files so that I can try to understand what the options are?

Collaborator

DarwinAwardWinner commented Dec 10, 2012

M-x describe-variable el-get-sources includes documentation on all of the properties that can go in a recipe. But that is not a guide to writing a complete recipe.

Contributor

zwass commented Dec 10, 2012

This is very helpful. Perhaps worth adding a reference in the README.

On Sun, Dec 9, 2012 at 7:34 PM, Ryan Thompson notifications@github.comwrote:

M-x describe-variable el-get-sources includes documentation on all of the
properties that can go in a recipe. But that is not a guide to writing a
complete recipe.


Reply to this email directly or view it on GitHubhttps://github.com/dimitri/el-get/issues/983#issuecomment-11178549.

Owner

dimitri commented Dec 10, 2012

Did you read the (info "(el-get) Authoring Recipes") Info book pages?

Owner

dimitri commented Dec 14, 2012

When writing the info document I didn't want to duplicate the el-get-sources online documentation, but maybe that's exactly what needs to be done. Do we have any mechanism to then keep the info file in sync with the embedded doc string?

Collaborator

DarwinAwardWinner commented Dec 14, 2012

I think the doc string should simply link to the info document. Doc strings aren't really supposed to be that long anyway. The doc string should document the structure of the variable, and refer to the info pages for information on what each of the properties mean.

Contributor

zwass commented Dec 14, 2012

I'm in agreement with @DarwinAwardWinner. I had read the info document, but for some reason that text didn't register with me.

Owner

dimitri commented Dec 14, 2012

Well it's not how it is done in Emacs itself, see C-h f interactive RET to see for yourself...

Collaborator

DarwinAwardWinner commented Dec 14, 2012

Good point. The documentation for interactive is duplicated in both the doc string and the info pages. But it is clearly a manual duplication in that case, with no automated method to keep it in sync, as the descriptions are worded slightly differently in the two sources.

If the info source files have some way to run a command and inline the output or something like that, we could write a script to extract the doc string and reformat it into info syntax. Other than that, I don't see how to keep them in sync.

Can one modify the docstring of a function programmatically after defining the function? That could potentially allow the elisp code to read the info file and splice it into the doc string.

Owner

dimitri commented Dec 14, 2012

For now I'll just byte the bullet and manually add the text to both files...

dimitri closed this Dec 14, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment