Fix invalid references in manual.tex

[bangerth]

There are a bunch of invalid references when compiling the manual, including but not limited to things like this:

LaTeX Warning: Hyper reference `parameters:Material_20model/Simpler_20with_20cr
ust_20model' on page 97 undefined on input line 3.

[97 <./cookbooks/free_surface/free_surface_blob.png> <./cookbooks/free_surface/
free_surface_topography.png>]

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Reference density' on page 98 undefined on input line 4.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Reference specific heat' on page 98 undefined on input line 5.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Reference temperature' on page 98 undefined on input line 6.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Thermal conductivity' on page 98 undefined on input line 7.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Thermal expansion coefficient' on page 98 undefined on input line 8.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Lower viscosity' on page 98 undefined on input line 13.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Upper viscosity' on page 98 undefined on input line 14.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Jump height' on page 98 undefined on input line 15.
LaTeX Warning: Hyper reference `parameters:Material_20model/Simpler_20with_20cr
ust_20model' on page 97 undefined on input line 3.

[97 <./cookbooks/free_surface/free_surface_blob.png> <./cookbooks/free_surface/
free_surface_topography.png>]

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Reference density' on page 98 undefined on input line 4.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Reference specific heat' on page 98 undefined on input line 5.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Reference temperature' on page 98 undefined on input line 6.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Thermal conductivity' on page 98 undefined on input line 7.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Thermal expansion coefficient' on page 98 undefined on input line 8.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Lower viscosity' on page 98 undefined on input line 13.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Upper viscosity' on page 98 undefined on input line 14.

LaTeX Warning: Hyper reference `parameters:Material model/Simpler with crust mo
del/Jump height' on page 98 undefined on input line 15.

We should really try to go through these and figure out how this can be addressed.

These errors can all be found by doing cd doc ; make manual.pdf and then looking into doc/manual/manual.log.

[alarshi]

I want to take it if no one else is already working on it.

[bangerth]

@alarshi -- please go right ahead!

I suspect that we are referencing parameters that have moved to other sections, but haven't really gotten into it. Pick the first missing reference and see what is happening there. Feel free to ask questions here about anything that may not be obvious!

[tjhei]

Simpler with crust is from a cookbook with a plugin lib. Of course this means that its parameters won't be in parameters.tex. We could work around this by creating these labels manually linking to the same cookbook or ignore them (this is why I have ignored them in the past).

[alarshi]

I did not know how to approach the invalid references for the plugins like Simpler with crust and Prescribed boundaries.
The first warnings in the log file for invalid references for parameters in the parameters.tex were for the boundary velocity model in cookbooks/gplates because the parameters used have been modified in the gplates.cc file and not updated in the doc/manual/cookbooks/gplates/gplates.part.prm file. If I modify this file for the current part from the cookbooks/gplates-2d.prm file, the parameters are linked. I am not sure if this is the correct way want to fix the references.

[bangerth]

Yes, this is exactly the way to do it -- the .part.prm files in doc/manual/cookbooks/... should indeed match pieces from the larger .prm files under cookbooks/. It would be great if you could mirror the changes that were made to the latter into the former! Thanks in advance!

[bangerth]

@alarshi -- thanks for working on this! Is there anything you know is left for this issue, or can we close it?

[alarshi]

If we ignore the invalid references of parameters used in plugins and cookbooks, I think we can close it.

[bangerth]

I can think of ways to address these as well. Having looked at this, do you think it would be easy to find all of the places in the .prm files in doc/manual/cookbooks/... where we reference parameters that are only defined in the plugins specific to a particular cookbook?

If we could put a comment (like # NOLINK) at the end of the line, then I could pretty easily adjust the script that generates these references to exclude a particular line.

[alarshi]

I could surely do it but could you please confirm if I understood it correctly: For the first warning related to simpler_with_crust, I modified the corresponding file (manual/cookbooks/free_surface_with_crust/free-surface-wc.part2.prm) as:

subsection Material model
  set Model name = simpler with crust #NOLINK
  subsection Simpler with crust model #NOLINK
    set Reference density             = 3300 #NOLINK
    set Reference specific heat       = 1250 #NOLINK
    set Reference temperature         = 0.0 #NOLINK
    set Thermal conductivity          = 1.0 # low thermal conductivity for a sharp blob #NOLINK
    set Thermal expansion coefficient = 4e-5 #NOLINK

    # Parameters added for this cookbook:
    # The box is 200km high and has its origin set at the bottom left corner.
    # Setting the jump height to 170km creates a 30km thick crust
    set Lower viscosity               = 1e20 #NOLINK
    set Upper viscosity               = 1e23 #NOLINK
    set Jump height                   = 170e3 #NOLINK
  end
end

[gassmoeller]

This seems like a lot of work for everyone who writes a cookbook. Do you think the effort is worth it? Instead of modifying all of the .part.prm files, would there be a way to just tell the script: Ignore if this link is not found?

[tjhei]

This seems like a lot of work for everyone who writes a cookbook. Do you think the effort is worth it?

I agree.

Alternatives:

1. Just ignore the warnings.
2. Add all the missing references manually to each cookbook section.
3. Include the .prm (which has no links) instead of the .prm.out for cookbooks with plugins.

[gassmoeller]

I like option 3. It would rid us of the warnings, and the additional work of putting comments in many lines of the parameter files.

[bangerth]

The problem is that in most of the cookbook .prm files, almost all lines of course reference sections and parameters that really do exist in core ASPECT. And I find it useful to be able to click on them and get to see their documentation. It's also useful to see them in the index at the end of the PDF file and see where (which cookbook) they are actually used.

The only problematic ones are the ones that reference parameters that are only defined in a shared library specific to the particular cookbook or benchmark. The options we have:

• Just ignore the warnings
• Mark these particular parameters up somehow
• Do not cross-reference any parameters in the PDF and in the index I don't think 3 is an option. I could go with either 2 or 3.

[bangerth]

@alarshi : You almost got this right. In your example,

subsection Material model
  set Model name = simpler with crust #NOLINK   *********************************
  subsection Simpler with crust model #NOLINK
    set Reference density             = 3300 #NOLINK
    set Reference specific heat       = 1250 #NOLINK
    set Reference temperature         = 0.0 #NOLINK
    set Thermal conductivity          = 1.0 # low thermal conductivity for a sharp blob #NOLINK
    set Thermal expansion coefficient = 4e-5 #NOLINK

    # Parameters added for this cookbook:
    # The box is 200km high and has its origin set at the bottom left corner.
    # Setting the jump height to 170km creates a 30km thick crust
    set Lower viscosity               = 1e20 #NOLINK
    set Upper viscosity               = 1e23 #NOLINK
    set Jump height                   = 170e3 #NOLINK
  end
end

The line marked with ************** should not have the tag because that parameter is a core ASPECT parameter -- it's just the value that is specific to the plugin, but the parameter itself exists in ASPECT.

We could probably make everyone's life easier by modifying the script in such a way that if a subsection is marked with #NOLINK, then it ignores everything inside. @alarshi -- would that reduce the amount of work significantly?

[alarshi]

@bangerth: I understand, I can certainly do that.

[tjhei]

@bangerth before @alarshi puts too much effort into this: I think we should first finish the discussion and, after we agree that this is what we want, can we make the script work first?

[bangerth]

Yes, that's reasonable.

So what do you suggest, @tjhei ?

[bangerth]

No longer relevant.