On Sat, Oct 30, 2010 at 03:18:21PM -0500, Peter Samuelson wrote: > > [Hyrum K. Wright] > > Would it be possible to define a simple markup format, and then just > > put these strings in a text file and process that, similar to what we > > do with our sql statements now. Is there a markup format which > > already exists which would suit this purpose? > > I have to say I kinda like the git approach. 'git merge --help' > literally spawns 'man git-merge', which is a full-featured manpage, > including a references section and all that. For a tool that has no > ambitions to work on anything but a Unix platform, it seems like a > pretty good approach. I suppose it would be problematic for typical > Windows installs of the command line binaries. > > Maintaining real man pages is an idea I've toyed with in my brain for > quite some time.
I'll focus on content for now, and not on what file format or markup the help texts should live in. It's a separate issue so it can be dealt with separately. And I think the content is way more important than the format. That said, I think the embedded strings are fine. They always work on any platform and aren't hard to maintain. > I don't understand why it would be a bad thing to replace the book, at > least for usage, semantic information, and examples. There is no reason to replace the book. The book is a great resource, and will always provide a more thorough and complete picture. Stefan
