RFC - Do Not Merge, but please do read.

[warmstarter]

This is intended to demonstrate an idea and as is should not be merged into master. It is the bare minimum to demonstrate a concept.

asksource.sh is a rather large shell script that has both coded logic and useful textual information.

There are two reasons for making changes to this shell script:

1. Easier maintainability and readability of the code.

-- This is fairly obvious, and shell scripting is one of the things I'm better at, so I should be able to do a lot here.

2. Separating the information aspects from the code logic.

-- This makes things a bit cleaner, but the real reason is that by separating I can then work with it through the other scripts related to documentation. What you see in 'make confsource' has good info at a glance or for experts, but there's a lot more that can be said on this topic. By making this separation, this information can be used as is in 'make confsource' and with that it can also be easily called by documentation projects. Basically any chance to this information will go into the documentation, they will be in sync and only one will have to be maintained. You have the general concept seen within asksource.sh and it also serves as the introduction within a larger documentation system. The documentation then goes on to expand on it, link to related materials, give example code, explain trade-offs, things like that. I think you can see why that would be valuable.

The way I did this is not the exact way it has to be done. It's a quick and minimal sample to get you thoughts and comments on both the project and the implementation. In addition to that, I hope that it gets you thinking a bit about the more documentation elements within the code. How do you keep them in the sync? How does the documentation side automatically extract those elements?

'make confsource' is one of the first things people are going to encounter when trying to build RhostMUSH. Imagine if a Handbook had a chapter on every option, starts with what's in the code, and then expands and explains. Without this being considered in some way, it's going to cause duplication and rot of knowledge.

There may be a better way to do this, and there may be more places in which to do this, but take a look and give your thoughts. I work well with constructive feedback, and if you're not into it, no problem. It's your project, I'm just trying to learn it and do my best to contribute back.