To provide a standard README file for each rumprun package, a template system should be implemented. An existing structure that we could loosely follow is the pkgsrc system. Pkgsrc generates READMEs from variables in a Makefile.
- Once a maintainer creates, or updates, a package, they would run `make readme`. - Each Makefile contains an include for ../Makefile.inc. - ../Makefile.inc could include mk/rump.pkg.readme.mk. - mk/rump.pkg.readme.mk calls a script in scripts/ to generate the README.md based on Makefile variables. - Maintainer commits, Github can parse the README Generally following the pkgsrc naming convention, a rumprun package would have the following variables placed at the top of the Makefile: - - - - - DISTNAME= <pkg name>-<version> CATEGORIES= <following pkgsrc categories> MASTER_SITES= http://www.all.the/files/ MAINTAINERS= "Full Name" <[email protected]>,"Distinguished Full Name, Esq." github: @fnesq HOMEPAGE= http://url.to.site.homepage COMMENT= This library is linked to by other rumprun packages LICENSE= to ill NOTES= NOTES EXAMPLE= EXAMPLE - - - - - I've included CATEGORIES, even though rumprun packages don't have them. Maybe it isn't needed yet. I've added the EXAMPLE variable, which would pull from a file. Most rumprun packages have an example included in the README. I've added the NOTES variable, which would also pull from a file. Some packages may have additional information that the user needs to know about. Redis only works with one type of persistence, for example. Mysqld disables threads, as another example. We could make some variables required. Possibly MAINTAINERS, DISTNAME and COMMENT would fit that need. Pkgsrc generates HTML README files. I would argue for Markdown. Markdown is easier to read in vim, and Github will parse Markdown automatically. This template resembles the majority of existing rumprun packages: - - - - - # Overview of ${DISTNAME} ${COMMENT} Source files are retrieved from [${MASTER_SITES}](${MASTER_SITES}). More information about the package can be found at [${HOMEPAGE}](${HOMEPAGE}). This package uses the ${LICENSE} license. # Maintainer * ${MAINTAINER[0]} * $(MAINTAINER[1]} # Additional Information ${NOTES} # Example ${EXAMPLE} - - - - - We could also include standard links in the READMEs pointing to the FAQ and build-rr tutorials. This is getting rather long. Any thoughts, obvious problems?
