CDR Tickets

It seems that one very big problems for inexperienced users of our publishing software is understanding the meaning and proper values for the parameters.

We have long suspected that some of these parameters are never used. I decided to find out if that was the case.

There are 17 distinct parameter names used in our "Primary" PublishingSystem XML document. What follows is a sorted list of all of the unique ParmName names used in either of our PublishingSystem documents ("Primary" and "QcFilterSets").

• AbortOnError

• CheckPushedDocs

• DTDFileName

• DateFirstPub

• GKPubTarget

• GKPushJobDescription

• GKServer

• IgnoreGKJobIDMismatch

• InteractiveMode

• MaxDocUpdatedDate

• NumDocs

• NumDocsPerDocType

• PubType

• ReportOnly

• RerunFailedPush

• SubSetName

• ValidateDocs

All 17 are used in the Primary doc. A subset of 10 of them are used in the QcFilterSets PublishingSystem XML document

I wrote a script to search for each of these in the SubsetSQL scripts embedded in the PublishingSystem XML documents. Only three of them were referenced in the SQL:

• MaxDocUpdatedDate

• NumDocs

• NumDocsPerDocType

I searched for the other 14 to see whether any of the ParmNames not used in the PublishingSystem document SQL are used in Python or C++ code. I searched all Python code in the following directories:

• \cdr\Publishing

• \cdr\lib\Python

• ...\cgi-bin\cdr

And I searched all .cpp and .h files in the Server directory. All of my searches were done in the Ampere tree because that was the latest for which I had everything checked out and I was pretty sure that even trunk would have worked for this purpose.

Every single one of the ParmNames that was not refernced in the SQL was referenced at least once in the Python code.

I therefore conclude that, although some parameters may be set in some publishing subsets and not actually used, there are no extraneous parameters relative to the entire CDR publishing system. There is at least some code that uses each of the parameters. I can't prove that it's called, but I can prove that it's there.

We have long suspected that some of these parameters are never used.

I guess the not being used is meant in terms of never, ever modify the default rather than it's not used anywhere in the code.
One of those do-not-touch parameters, for instance, is the checkbox for the re-publishing interface labelled Include linked documents not on Cancer.gov and I believe a parameter that's not displayed on the web interface anymore called something like include linked documents for the Hot-Fix Export is also a candidate.

Adding link to existing ticket. Some of the comments listed there relate to the current ticket.

I would like to propose a change to the publishing user interface to add the following capabilities:

• Hyperlink each parameter name to a description of what the parameter does.

• Make the default value unchangeable for parameters that should not be changed.

These require some changes to the Publishing.py program, some possible additions to PublishingSystem control documents (or maybe not, depending on whether there are some parameter values that should sometimes be changed and other times not), and some additional information stored either in the script or, given the difficulty of changing the scripts in the CBIIT environment, in the database.

I've got some ideas about this to discuss.

The above comment is in addition to some of the ideas in OCECDR-2220, as linked by Volker. I'll go through all of them and make some design notes on what would be involved in implementing them.

Hyperlink each parameter name to a description of what the parameter does.

Alternatively, we could just add ALT attributes to display the help on hover.

Make the default value unchangeable for parameters that should not be changed.

I think I'm against this change. I would much rather add to the description the reasoning for not changing a specific parameter. There are two parameters that come to mind that should not be changed by anybody but myself or somebody who knows what he's doing. Making these values unchangeable defeats the purpose of introducing the parameters in the first place.

... we could just add ALT attributes ...

ALT attributes are easier to add but I'm thinking that some long, formatted text might be appropriate for some of the parameters. However, ALT's are better than nothing, which is what we have now.

... Making these values unchangeable defeats the purpose of introducing the parameters in the first place.

One parameter I have in mind that should never be changed is PubType. If that one is wrong, the user should press the back button on the browser and choose a different SubsetName. It's possible that's the only one. If it is, then a general purpose mechanism for suppressing changes does sound like overkill. It might be enough to just put instructions in the descriptive (or ALT) text saying not to change this.

Update/validate existing documentation inside the publishing control documents (XML).

There are no links to commits in this issue, nor any indication in the comments that any of the work to modify the publishing control document was ever performed, so I'm pulling this out of Darwin. We can do the work outside of any release, as modifications to the publishing control document (where the UI documentation is stored) can be promoted without CBIIT's assistance.

This has been done as part of previous releases/work on other tickets.