Know issues with building the manual

[Iximiel]

I am opening this discussion as a TODO list, the curiositi around the manual started with a check that the things I changed in Keywords have no impact on the outside world:

Currently not everything in the manual renders correctly (cor example the Continuation lines page):
I downloaded the raw output of one of the latest run and I grepped a few things out of it, the files that origins the errors are not listed, i think due to that >/dev/null in the CI file:

Some errors give no problem, some completely break a page, I do not have a clear criterion for that.
I think part of this came form plumed, and part from the user-doc script, but I did not found a specific criterion, so I compiled this as a starting point:

• cat: ../regtest/basic/rt-make-load-cpp: Is a directory the procedure enters in the plugins and in the regetests with a cat ../*/*/*cpp, easily solvable with a dot: cat ../*/*/*.cpp

if I grep 'is not known':

• Action "EUCLIDEAN_DISSIMILARITIES" is not known. I think now is only DISSIMILARITIES??? (but no mention of this change in CHANGES/*)
• Action "COLUMNSUMS" is not known.
• Action "COLUMNSUMS" is not known.
• Action "0" is not known.
• Action "MTRANSFORM_MORE" is not known.
• Action "974,985,1007,1018,1037,1247,1264,1283,1302,1324,1689,1708,1727,1738,1962,1984,1994,2312,2329,2349,2467,2490,2500,2517,2524,2536," is not known.
• Action "SPECIES1=1-26" is not known.
• Action "CHECK_CONSISTENCY" is not known.
• Action "PYTHONCV" is not known. I think I have to address this by making pycc avaiable while building the doc to get ( the procedure enters in the plugins with a cat ../*/*/*cpp that makes it enter also into the regtests )
• Action "PYCVINTERFACE" is not known.
• Action "PYTHONCV" is not known.
• Action "PYTHONCV" is not known.
• Action "PYTHONCV" is not known.
• Action "PYTHONFUNCTION" is not known.
• Action "EUCLIDEAN_DISSIMILARITIES" is not known.
• Action "EUCLIDEAN_DISSIMILARITIES" is not known.
• Action "EUCLIDEAN_DISSIMILARITIES" is not known.

If I grep ERROR doc_err.dat, I think some of these are due to the preprocessor that "eats" the # for some comments

In spoiler since they are 126!!!

• ERROR in input to action ANN with label ann : cannot find action named l_0_out_0 (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver )
• ERROR in input to action CAVITY_CALC with label cav : number of atoms in box should be equal to four
• ERROR in input to action CAVITY_CALC with label cav : number of atoms in box should be equal to four
• ERROR in input to action DFSCLUSTERING with label dfs : keyword ARG is compulsory for this action
• ERROR in input to action SORT with label @s12 : action cn has no component named v-0 (hint! the components in this actions are: cn )
• ERROR in input to action DUMPGRID with label @32 : keyword ARG is compulsory for this action
• ERROR in input to action DFSCLUSTERING with label dfs : keyword ARG is compulsory for this action
• ERROR in input to action DUMPCUBE with label @33 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @31 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @14 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @31 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @31 : keyword ARG is compulsory for this action
• ERROR in input to action METAD with label md : cannot find action named d (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver t )
• ERROR in input to action ENVIRONMENTSIMILARITY with label @s9 : missing input file env1.pdb
• ERROR in input to action ENVIRONMENTSIMILARITY with label @s9 : missing input file atom-names.pdb
• ERROR in input to action FOURIER_TRANSFORM with label @0 : keyword ARG is compulsory for this action
• ERROR in input to action FUNCPATHGENERAL with label path : cannot find action named d1 (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver )
• ERROR in input to action FUNCPATHGENERAL with label path : cannot find action named d2 (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver )
• ERROR in input to action FUNNEL_PS with label fps : missing input file start.pdb
• ERROR in input to action FUNNEL_PS with label fps : missing input file ref.pdb
• ERROR in input to action FUNNEL_PS with label fps : missing input file protein.pdb
• ERROR in input to action PRINT with label @37 : found no element in p2 with label X
• ERROR in input to action HBOND_MATRIX with label mat : cannot understand the following words from the input line : SUM
• ERROR in input to action DUMPGRID with label @31 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @14 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @31 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @31 : keyword ARG is compulsory for this action
• ERROR in input to action RESTRAINT with label @s9 : cannot find action named t (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver )
• ERROR in input to action RESTRAINT with label @s9 : cannot find action named t (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver )
• ERROR in input to action INCYLINDER_CALC with label d2 : should only be one atom specified
• ERROR in input to action INTERPOLATE_GRID with label ii : keyword ARG is compulsory for this action
• ERROR in input to action MAZE_RANDOM_ACCELERATION_MD with label rw : keyword OPTIMIZER_STRIDE could not be read correctly
• ERROR in input to action MAZE_SIMULATED_ANNEALING with label sa : keyword COOLING_SCHEME is compulsory for this action
• ERROR in input to action MAZE_STEERED_MD with label smd : keyword OPTIMIZER_STRIDE could not be read correctly
• ERROR in input to action CUSTOM with label @s29 : cannot find action named dens (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver grid_dist grid_inumer_sigma grid_inumer_cov grid_inumer_icov grid_inumer_bwprod_vec grid_inumer_bwprod_logs grid_inumer_bwprod_logsum grid_inumer_bwprod grid_inumer_vol )
• ERROR in input to action DUMPCUBE with label @58 : keyword ARG is compulsory for this action
• ERROR in input to action DFSCLUSTERING with label dfs : keyword ARG is compulsory for this action
• ERROR in input to action PAMM with label @s16 : keyword ARG is compulsory for this action
• ERROR in input to action PCA with label @s36 : keyword ARG is compulsory for this action
• ERROR in input to action PCA with label @s35 : keyword ARG is compulsory for this action
• ERROR in input to action PCAVARS with label @s9 : could not open reference file reference.pdb
• ERROR in input to action PCAVARS with label @s15 : could not open reference file epath.pdb
• ERROR in input to action DUMPATOMS with label @18 : cannot find action named q3_anorm (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver q3_mat q3_sh q3_denom_ones q3_denom q3_sp q3_norm2 q3_norm q3 q3_mean )
• ERROR in input to action DUMPATOMS with label @18 : cannot find action named q4_anorm (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver q4_mat q4_sh q4_denom_ones q4_denom q4_sp q4_norm2 q4_norm q4 q4_mean )
• ERROR in input to action DUMPATOMS with label @18 : cannot find action named q6_anorm (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver q6_mat q6_sh q6_denom_ones q6_denom q6_sp q6_norm2 q6_norm q6 q6_mean )
• ERROR in input to action QUATERNION_VECTOR with label q1 : keyword ATOMS could not be read correctly
• ERROR in input to action DUMPGRID with label @32 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @33 : keyword ARG is compulsory for this action
• ERROR in input to action CONTACT_MATRIX with label @s11 : missing SWITCH11 keyword
• ERROR in input to action TETRAHEDRALPORE_CALC with label cav : number of atoms should be equal to four
• ERROR in input to action CAVITY_CALC with label cav : number of atoms in box should be equal to four
• ERROR in input to action DUMPGRID with label @16 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @16 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @16 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @16 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPVECTOR with label @8 : keyword FMT could not be read correctly
• ERROR in input to action DUMPVECTOR with label @8 : keyword FMT could not be read correctly
• ERROR in input to action DUMPVECTOR with label @8 : keyword FMT could not be read correctly
• ERROR in input to action DUMPVECTOR with label @8 : keyword FMT could not be read correctly
• ERROR in input to action DUMPGRID with label @29 : keyword ARG is compulsory for this action
• ERROR in input to action DUMPGRID with label @29 : keyword ARG is compulsory for this action
• ERROR in input to action GROUP with label @0_grp : atoms specified using @ symbol but no MOLINFO was available
• ERROR in input to action RESTRAINT with label @s9 : cannot find action named dist (hint! the actions with value in this ActionSet are: timestep kBT posx posy posz Masses Charges Box driver )
• ERROR in input to action CUSTOM with label @s18 : cannot find action named s (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT c1 c_mat c_ones c c_caverage )
• ERROR in input to action REWEIGHT_BIAS with label ww : found no actions with a component called bias
• ERROR in input to action PRINT with label @5 : cannot find action named cos (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT t c1 c2 d )
• ERROR in input to action BRIDGE_MATRIX with label w1_mat : problem reading SWITCH keyword : R_0 is required for RATIONAL
• ERROR in input to action PRINT with label @1 : cannot find action named aaa (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT cell )
• ERROR in input to action PRINT with label @2 : cannot find action named distance (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT dist )
• ERROR in input to action PRINT with label @3 : cannot find action named sss (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT cn dis )
• ERROR in input to action PRINT with label @3 : cannot find action named c2 (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT c1 x )
• ERROR in input to action MORE_THAN_VECTOR with label @0_mt : problem reading SWITCH keyword : R_0 is required for RATIONAL
• ERROR in input to action METAD with label @4 : cannot find action named diff (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT dAB dAC )
• ERROR in input to action PRINT with label @4 : cannot find action named theta (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT d1 d2 )
• ERROR in input to action PRINT with label @2 : cannot find action named m (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT d )
• ERROR in input to action METAD with label @3 : cannot find action named dz (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT c d )
• ERROR in input to action CUSTOM_VECTOR with label @0_diffs : all vectors input should have the same length
• ERROR in input to action CUSTOM_VECTOR with label @0_diffs : all vectors input should have the same length
• ERROR in input to action ECV_CUSTOM with label ecv : cannot find action named t1 (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT ene )
• ERROR in input to action ECV_MULTITHERMAL with label ecv : cannot find action named intEne (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT ene vol )
• ERROR in input to action EDS with label eds : cannot find action named dist2 (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT dist )
• ERROR in input to action EDS with label eds : cannot find action named dist2 (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT dist )
• ERROR in input to action EDS with label eds : cannot find action named dist2 (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT dist )
• ERROR in input to action PRINT with label @9 : action es has no component named mean (hint! the components in this actions are: es )
• ERROR in input to action MORE_THAN_VECTOR with label es_mt : problem reading SWITCH keyword : R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label d_mat : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action FUNCPATHMSD with label p1 : cannot find action named t1 (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT )
• ERROR in input to action PRINT with label @0 : cannot find action named rg (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT )
• ERROR in input to action CONTACT_MATRIX_PROPER with label c1_mat : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label lq3_cmap : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label lq3_cmap : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label w3_cmap : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label lq4_cmap : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label lq4_cmap : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label w4_cmap : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label lq6_cmap : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label lq6_cmap : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label w6_cmap : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action PRINT with label @4 : cannot find action named uwall (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT d1 d2 )
• ERROR in input to action PRINT with label @2 : cannot find action named m (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT d )
• ERROR in input to action CONTACT_MATRIX_PROPER with label @0_mat : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action BIASVALUE with label Ftg : cannot find action named FtgValue (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT phi )
• ERROR in input to action OPES_METAD with label opes : cannot find action named xx (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT phi psi )
• ERROR in input to action PRINT with label @27 : cannot find action named p1 (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT p1_data_ref p1_data_cpos p1_data_pos p1_data p1_mindist p1_weights p1_denom p1_z p1_zpath p1_ind p1_s_prod p1_numer p1_s p1_spath )
• ERROR in input to action PRINT with label @21 : cannot find action named pp (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT t1 t2 pp_gpath_ref_t1 pp_gpath_ref_t2 pp_gpath_data_t1_diff pp_gpath_data_t2_diff pp_gpath_data pp_gpath_ind pp_gpath pp_gspath pp_gzpath )
• ERROR in input to action PRINT with label @3 : cannot find action named pcse (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT nh enh st )
• ERROR in input to action PRINT with label @4 : cannot find action named pw (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT dist1 dist2 )
• ERROR in input to action BETWEEN_VECTOR with label q3_bt1 : Lower bound is higher than upper bound
• ERROR in input to action BETWEEN_VECTOR with label q4_bt1 : Lower bound is higher than upper bound
• ERROR in input to action BETWEEN_VECTOR with label q6_bt1 : Lower bound is higher than upper bound
• ERROR in input to action PRINT with label @6 : cannot find action named rdce (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT nh erdc st svd esvd st_svd )
• ERROR in input to action PRINT with label @6 : cannot find action named rdce (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT nh erdc st svd esvd st_svd )
• ERROR in input to action PRINT with label @4 : cannot find action named restraint (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT d1 d2 )
• ERROR in input to action REWEIGHT_TEMP_PRESS with label temp_press_weights : cannot find action named renergy (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT energy distance mybias bias_weights )
• ERROR in input to action REWEIGHT_TEMP_PRESS with label temp_press_weights : cannot find action named renergy (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT energy volume mybias bias_weights )
• ERROR in input to action PRINT with label @14 : cannot find action named avg_density (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT volume mybias bias_weights temp_press_weights avg_vol_wsum avg_vol_weight avg_vol_denom avg_vol_prod avg_vol_numer avg_vol )
• ERROR in input to action REWEIGHT_TEMP_PRESS with label temp_press_weights : cannot find action named renergy (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT energy volume mybias bias_weights )
• ERROR in input to action MORE_THAN_VECTOR with label @0_mt : problem reading SWITCH keyword : R_0 is required for RATIONAL
• ERROR in input to action PRINT with label @8 : cannot find action named sort (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT d12 d13 d14 d15 )
• ERROR in input to action PRINT with label @49 : cannot find action named ss (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT mat11 mat22 mat12 mat21 mat ss_diag ss_sp ss_selection1_mask ss_selection1 ss1 ss_coord-0 ss_coord-1 ss_coord-2 ss_coord-3 ss_coord-4 ss_coord-5 ss_coord-6 ss_selection2_mask ss_selection2 ss2 ss_coord-7 ss_coord-8 ss_coord-9 ss_coord-10 ss_coord-11 ss_coord-12 ss_coord-13 )
• ERROR in input to action CONTACT_MATRIX_PROPER with label tt_mat : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action CONTACT_MATRIX_PROPER with label tt_mat : problem reading switching function description R_0 is required for RATIONAL
• ERROR in input to action PRINT with label @4 : cannot find action named uwall (hint! the actions with value in this ActionSet are: posx posy posz Masses Charges Box mdcode kBT d1 d2 )
• ERROR in input to action UPPER_WALLS_SCALAR with label Snout : cannot understand the following words from the input line : In, this, same, interlude, it, doth, befall.
• ERROR in input to action RESTRAINT_SCALAR with label @4 : cannot understand the following words from the input line : indentation, is, not, required, (this, is, not, python!), but, makes, the, input, easier, to, read
• ERROR in input to action RESTRAINT_SCALAR with label @4 : cannot understand the following words from the input line : indentation, is, not, required, (this, is, not, python!), but, makes, the, input, easier, to, read
• ERROR in input to action RESTRAINT_SCALAR with label @4 : cannot understand the following words from the input line : indentation, is, not, required, (this, is, not, python!), but, makes, the, input, easier, to, read

@GiovanniBussi @gtribello @carlocamilloni @maxbonomi we may use this discussion as "easy to reach" dump for the manual issues

[Iximiel]

I discovered that by chcking the css with overflow: visible; in the right place the tooltip that you get by hovering the mouse on the keywords will not be clipped by the border of the listing

[gtribello]

Hello all

Please don't forget that I did some work on a new version of the manual. You can see where I am with this here.

https://gtribello.github.io/plumed-manual/

I have also been working on writing documentation for many things that are currently undocumented in the master version of PLUMED. I am not really worrying about making this new documentation work with the old manual building system because that old code is a mess. It produces a manual that we don't like the appearance of. As evidence of that fact, we have had at least one attempt in the past to replace the manual (by Max) that fizzled out.

My point is that if we are going to fix the manual, let's make sure that we have agreed on a common approach first. My preference is to throw away the old manual builder and develop a new system. This doesn't necessarily have to be exactly what I have done above, but the features that I am really keen to keep are:

1. Ensure that we are using PlumedToHTML to render all plumed inputs so that we do not have to maintain two pieces of code that do the same thing.
2. Have a minimal amount of top-down order in the manual. I would get rid of the parts of the manual that break things down in terms of colvars, functions and biases. I have a page with the list of actions and pages for each of the modules and actions. I chose that approach as that is the way we have organised the code. I think that it is sufficiently simple for contributors from the community to be able to follow it. I think the various categories that we had in the old manual is one reason why it is a mess.
3. Link documentation on manual pages for actions and modules to examples in the nest and tutorial. In that way, we ensure that every action/module has some examples for people to look at even if no one actually bothers to write documentation for their action.

I think it would also be good to add in functionality to allow users to interact with the manual using a chat bot. However, I don't really know how to do that.