Update rpt.conf to Remove Uncommon Options #621
Conversation
Remove remote base and DAQ config options that are rarely used (remote base) or currently unsupported (DAQ), and are just adding clutter and confusion to rpt.conf. ASL manual will document all the available config options and their usage, should users want/need to enable those options. This cleans up the default template for new users.
|
Since there are already comments for these, these should be moved to the sample file (which doesn't exist yet) before being removed |
|
Thinking out loud: would it make sense to group uncommon "stuff" together with a comment about it being uncommon? |
|
We could also move the uncommon "stuff" into one or more #include files. |
The sample file is the one with every option in it. |
|
... and the plan is to add documentation to the code and then generate the sample files (with everything documented) using https://github.com/InterLinked1/astsamplegen |
I have commented pretty much every option I have found (so far) in the pending rpt.conf PR that is going into the manual. There are a few "undocumented" ones I still need to track down. I've gone through all the existing rpt.conf examples floating around, and tried to capture all the settings to get them all documented. My thoughts on this PR is that for the majority of users, there are options in the installed sample rpt.conf that they will never use (remote base stuff) or aren't even currently supported (DAQ... I have an idea on how to support that in the future though). So, for readability purposes, I feel it makes sense to get rid of the clutter, and only include the options that they must have to make a functioning system, or are likely to want to customize. In addition, some of the stuff, like the [remote-functions], is unreachable. Unless you specifically name that stanza in the node config to pull it in, it is orphaned, and will be ignored. As I work through building more manual pages, my intent is to include sample code blocks of configs that can be added to the user's rpt.conf to enable those features... but that will be a work in progress, and will take a number of iterations, until everything is in the manual, and all the cross-references are added. |
That's probably a decent way to manage some of the more uncommon features. It would keep some of the clutter out of the main rpt.conf file, and group the related/required settings for the option into one place. |
This is still sort of a proof of concept... not sure if the tool is that mature yet. |
See: |
I'm talking about XML documentation in the code, not any external documentation that may exist elsewhere. For the purposes of this repo, that doesn't count. |
Can you point to this XML documentation you refer to? I must not be looking in the right place. Regarding sample docs... sure I can write some samples to put in, and add some includes to pull the samples in to rpt.conf. |
That's just it, there isn't any currently for any of the radio modules, it's part of the backlog to add some so that all the options are documented there. Here is an example of a module that has documentation: https://github.com/asterisk/asterisk/blob/master/apps/confbridge/conf_config_parser.c#L44
I think Allan wants to experiment with not working on samples for the moment to see if we can autogenerate them. If somebody wants to do that, that's certainly great, but I think the XML documentation alone will probably be more valuable right now. |
Correct. We can spend our time updating the .conf files, adding .sample files, adding comments into the code, and updating all of the above whenever changes to be needed. Or, we can focus our efforts. By adding the XML documentation (into the code) we can use tools to create/update all of the other content. That also puts the truth in one place. |
to pull those config files in, if they exist.
Ok, I can have a look and see if I can help with some of the XML documentation... once I finish working on the ASL3 manual conversions I'm working on. In regards to this PR. I've moved the removed settings to sample files, and adjusted rpt.conf to pull in the additional conf files for those features. |
The sample configs aren't quite right... there should only be one |
|
@Allan-N do we want this one resolved and merged or is it dead at this point? |
Documentation should not be deleted. Since the |
|
I really don't want to close this PR. I also don't think it's ready to be merged. Long term, we should be updating the code with all of the variables, defaults values, descriptions, etc and then use that to generate / update the online documentation, sample files, etc. But, I don't see us doing that with this PR. For this PR, I think the question is whether we want to extract out the uncommon (blocks of) options into separate #include/#tryinclude .conf files. |
The goal is/was to try and clean up What's the best path forward? I don't know. But Allan's suggestion of hiving some of this off into something like a |
The proper solution is they are all in the sample config, but that doesn't currently exist. |
4 participants
Remove remote base and DAQ config options that are rarely used (remote base) or currently unsupported (DAQ), and are just adding clutter and confusion to rpt.conf.
ASL manual will document all the available config options and their usage, should users want/need to enable those options.
This cleans up the default template for new users.