If it is a configuration file, I really like to also have the unused parameters commented out but in the configuration file, especially if it is a configuration file that I almost never look at, for example the Exim4 mail daemon configuration file.

If it is a configuration file that everybody looks at all the time, all the unused options are known to everybody and only clutter up the file making it hard to see what is really used/active.

I guess what I'm saying is that I can see both approaches having their benefits and you maybe need to investigate further which parts everybody knows and which parts people want/need examples of. Maybe you can move the examples to a different file where people can copy from.

I think this is like asking the best way to make a bacon butty, everyone has their own opinion.

For my personal preference, everything listed, and unused sections/values explicitly marked with something very obvious, eg "***UNUSED***", that will not be processed as 0, nil, null, the empty string or any other legitimate value.

If its done right, it gives a one file specification and data, everything together and self-documenting db.

The only cogent argument I remember against it is that if it is a public file, it can give "the bad guys" an insight to the internals.

That said, if you ever had to try to maintain or compare Apache config files ... :(

A common good practice (as I see it) is to have a fully-fledged configuration file example in the documentation, e.g for a Linux based distribution foo a file /usr/share/doc/foo/example/foo.conf.example - that way the actual configuration file /etc/foo/foo.conf can be kept clean without clutter.

Don't know about Windows best practices though. A Windows Help File pair *.chm/*.chw comes to mind, which would contain all possible configuration items.

Some useful thoughts, thanks... The scale and "interface" (such that it is) is an issue, though.... and warrants some further explanation of what we're dealing with...

An example of a (tiny) section:-

123:
A1=12:MSMA=32:PX=2:
RP=12,23:
[download]

Currently, there are ~12,000 sections (each containing perhaps up to 100 lines of code, similar to that shown above), with many 100s of the sections being unused at any given time. At most, there can be something like 65,000 entries in this plain text file... and the sections need to be managed manually - there is no control/dependency enforced regarding the section and the application "module" that refers to it; in fact, many modules can refer to the section, in a number of ways... but you have to know the modules that refer to the section - there is nothing in the application which provides the "reverse link". The application provides a very rudimentary text editor (not as useful as a Windows "Notepad") to maintain the text file in which these sections are stored.

The application is something that's moved between platforms (PDP/RSX -> VAX/VMS -> PC/Windows) during the last 40+ years it's been in use... so the text file has been managed with line editors, external screen editors and now has its own "internal" text editor... but the basic design/structure hasn't changed - the software vendor considers this "interface" as adequate for managing all the sections.

Hence, having very many "unused" sections introduces a lot of "noise" when trying to locate sections, examine the contents of the sections, etc... and as every section is "free-form" text (more-or-less), most people who have used the file over the years have never added useful identifiers to the sections (such as author, date of use, what other components of the application *use* the section, application notes of the section, etc) which help to decide whether the section is in-use, critical, expired, etc, although there has always been the concept of a "comment line" - it's simply that most users have decided to rarely use any comments(!)

Sure, we have built some tools to help us check the dependencies, the contents of the sections, etc... but the users still tend to want to be able to see "all" of the sections they might be interested in collected together in the one place in the file (perhaps 10 or more, 100-line sections)... and want to have them ALL in the file "just in case". Others find it annoying to have to work through each individual section, finding some to be "unused", when they're trying to find specific code within each section... or, indeed, to locate a particular section they might want to work on.

Anyway, we have to get the files "cleaned-up" (there are currently 30+ of these files), removing unused sections, perhaps introducing some decent comments, etc... but some users agree to ACTUAL removal of the unused sections (the files are backed-up and are available on-line every day for the last rolling 2 years) and some want to keep everything in the file, even though the sections may become irrelevant over the time that elapses between uses ...and we're just looking to see if there's any approach to such a text file that's considered "good practice" when "removing" sections from the file... hence my weird question.

Take a look at how easy/convenient it is to make "old" information available elsewhere.

It seems to me that old configuration information is kept around in the file partly for version control information and partly because it might come in useful later.

In the case of version control, maybe, maybe you can move that part to a version control system like git or Mercurial. This will require support from all users, so that they also know where to look at older versions of the file. Maybe you can put the link to the repository viewer URLs at the top of the configuration file.

In the case of documenting history and/or old/other usages, it is much harder to move this to a different location, as people will likely differ on the terms to search for. In some situations I got buy-in from users using TiddlyWiki for documentation. In other situations, a long (long!) Word document where old topics get moved to the "done" section and current topics stay near the top of the document.

A third approach could be to create your own viewer(s)/editors for the document that hide commented-out lines or that reformat the "current" file with additional comments and maybe can link to relevant documentation etc. - but that introduces yet another tool to the set of tools that the users already have, and will need maintenance.

You are already talking to the actual users of the process, and while the process might be hated by everybody, it seems to already have worked for 40 years. Your replacement of the change process to these file(s) will have to take into account that there are some parts of the existing process that actually work and the new process ideally doesn't break the things that already work while improving the things that are currently preceived as risks or hard.

Consolidating the different files screams for something like version control and maybe a centralized process of changing the configuration file actually used in production. The daily backups are fairly close to version control already and people are likely also familiar with the process of retrieving a good version from the backup. Implementing a centralized process of updating the Master configuration will create a bottleneck there because if the person(s) doing that change are unavailable, no such change should happen. On the other hand, this will create a ground truth and eliminate the different versions of configuration files that people keep around for that one time they had to change that obscure thing.

You are already talking to the actual users of the process, and while the process might be hated by everybody, it seems to already have worked for 40 years. Your replacement of the change process to these file(s) will have to take into account that there are some parts of the existing process that actually work and the new process ideally doesn't break the things that already work while improving the things that are currently preceived as risks or hard.

This is the sort of thinking we've had behind adding some informative headers to the sections. The users can still do what they already do more-or-less BUT we introduce a process that does some reporting on those sections that are 'non-compliant' in terms of the headers the section includes.

Y'see, one of the problems is that the software we're talking about is totally 'closed' and we have no means of intercepting/controlling the input/usage/management of all these sections - we have to use the software to do all that - but there are text files of all the sections that are maintained 'live' by the software... and we can interrogate those text files with our own tools.

So, as far as the documentation of the sections is concerned, we were looking to develop some mandatory/optional headers to be included in the sections, with some application rules... and then our external tools would enforce the inclusion of those headers.

This would mean this current section:

123:
A1=12:MSMA=32:PX=2:
RP=12,23:
[download]

...would perhaps become something like:

123:
; Author: Fred Smith (smithr)
; Created: 12-Dec-2016
; Used by: MODV, MODS in XDR Region
; Purpose: Control the rate at which widgets collapse into wigwams
; Keywords: train, isolated, trim, summer
; Expires: 23-Dec-2016
;
A1=12:MSMA=32:   ; To set-up for the collapse
PX=2:
RP=12,23:        ; ...and into wigwams
;
[download]

I expect we'd supply some sort of template for users to fill-out and then paste the result into the software's text editor/input... and if our tools find something 'wrong' with the headers, it would be noted in a report.

I note that to get these folks to change their behaviour (and to get some management support about doing something to fix one of the problems that's been identified) will be/already is a significant battle... but they need to meet us somewhere half-way if they want to get their problems fixed, I reckon..

Anyway, this is something of a 'side issue', although I expect we'd get some good value out of it, as there are 1000s of sections with no documentation that the users constantly complain about... and get trashed/re-used accidentally.

Still thinking about the suggested options for how to actually manage the sections themselves...

I'm personally on the side of those who prefer clean configuration files, and a proper documentation on the nature of the configuration file which provides all necessary information about things possibly missing in the file which is actually used.

So, since you already have tools which check the dependencies, you could generate a hyperlinked documentation of those sections and their contained items, which could be checked just in case and, in the productive configuration files, just one line of comment for each missing section, according to the config files convention, containing a link to the missing section's documentation.

That way the "just in case" folks have their reference, and the others would see the clutter as having been drastically reduced.

perl -le'print map{pack c,($-++?1:13)+ord}split//,ESEL'