I am, as part of the AFST course, working on a free software project, Vox Anonymus. One of the requirements for the software is that it should come complete with documentation on how to install it (not at all unreasonable by any measure).
But I find asking myself how to handle this install information. I needs to be included in the INSTALL file, as well as on the website. At the same time, I feel the urge to not repeat myself. DRY (Don’t Repeat Yourself).
I’ve read up on some techniques, reStructured Text, python-docutils, etc. but I have been unable to find a suitable solution which would convert some simple text format to both (x)html and some reasonable plain text representation for the INSTALL file.
The simplest solution would probably be to use some mark-up language, and a formatting system, and then let the source file be the INSTALL file, from which the html file can be generated. This would leave some “mark-up artifacts” for the prospective users of the application.
Second easist solution: Have the html file be the source file, and generate the INSTALL file by stripping the tags out of the html file. While this would be acceptable, two things bother me:
- It could potentially take some work in order to make the stripping / reformatting perform properly (with regards to newlines, indentation, etc)
- Going against YAGNI (You Ain’t Gonna Need It), what if there is a future format I would wish to support?
(I will have to admit though, whilst browsing through “Beginning Python” by Magnus Lie Hetland (Apress) I discovered a chapter (20) outlining a simple system for doing just this, and it sparked my curiosity, so I might have been more than a little “influenced” to reject all other ideas ;))
The third option, then, the path I at least for the moment, have settled on, is to create a miniature mark-up syntax, with the accompanying formatter scripts, to allow for generation of both plain text and html, and extensibility for the future.
The final tipping point is that I can have more automation this way. With the first approach, this would have had to have been a tack-on ugly hack. With the second approach, since a couple of simple sed commands would have done the trick, and I would thus have employed a shell script to reformat the text I would have had to solve it manually, but now with the third option, it can be brought into the cor functionality;
The tarball I generate is given a filename consisting of the name of the project, as well as the version of the project, as can be found in setup.py. Hence, the web-page download link need to be updated every now and then. If I am generating the html, it would make sense to have python also generate an up to date link to the tarball.
Overall, this seem to have the makings of a good solution (all things considered) as well as being a good learning experience. Win-win.
But this was actually not what my post was supposed to be about. In the title, notice the question mark? With it I was not implying that I might be on to the best practice, but rather a question aimed at you, the readers. How would you have done it? Because there is bound to be better ways, with better motivations, than what I have cobbled up. There just has to be, since people have been putting together INSTALL instructions and other application documentation for free software for at least a good… what? thirty – forty? years. And there are bound to be those who doesn’t like repeating yourselves.