Manual contributions

Hello. What is the preferred approach for compiling the ASPECT manual with one’s own LaTeX compiler, like pdfLatex in the terminal? When I run pdfLatex on manual.tex I get numerous errors, like ! Package Listings Error: File cookbooks/overview/doc/simple.prm(.out)’ not fo
und.` I’m interested in compiling the manual myself so I can provide new content via a pull request.

Yes, lots of set-up is necessary to make that work. The easier approach is to do

  cd doc
  make manual.pdf

:slight_smile:

Cheers
W.

1 Like

This worked. Thank you.

I tried this approach, but I am getting this error. Do you have any suggestions?

I think that when we run make manual.pdf, we suppress any latex errors. That might not be our greatest idea, but on the bright side, make will have set all of the ancillary files up for you. So if this happens, you can go into the doc/manual subdirectory, and explicitly call pdflatex manual.tex there. This should now succeed, and if it doesn’t, it’s because you have errors in your .tex file.

That said, the error you show also mentions another way to find out what is wrong: check manual/manual.log.

Best
W.

Thank you for the feedback. I’ve tried recompiling in two different ways and I’ll describe what happened.

Approach 1: I updated ASPECT to account for your recent commit about this issue (#3880). I ran make manual.pdf and still was not able to compile. The log file indicates an emergency stop happens at line 3287 and the message is provided in a screenshot.

Approach 2: Following your suggestion above, I ran pdflatex manual.tex in doc/manual. The error message is in the second screenshot.

I’d be happy to fix this error and do a pull request, but I’m pretty new to LaTeX. If you have any suggestions, I can do a pull request if you would like to incorporate your suggestions. Thank you in advance.

Are you running an unmodified version of manual.tex through pdflatex? I’m asking because for me, the file compiles just fine. You should be able to see with git diff whether you have modifications in this file or any other that might get included into manual.tex has changes.
Best
W.

I have not modified the manual.tex file.

Dear Karen,

The manual compiles fine for me on the master branch. Rather than suggesting solutions (which would be guesses at this point), I’ll break down the problem in a bit more detail. Hopefully that will help.

The two errors you report describe part of the same problem. Line 3287 of manual.tex contains a reference to cookbooks/overview/doc/simple.prm.out. On Line 3 of that file is a hyper-reference to “parameters:Output directory”. The next non-empty line is Line 5, which contains the character string “{Geometry model”

The reference to “parameters:Output directory” refers latex to a third file, parameters.tex. This is an autogenerated file (we mortals should not play with it!). The file is (occasionally) generated by one of the ASPECT maintainers by running update_parameters.sh. We can run this shell script (it shouldn’t cause any errors), but it will modify manual/parameters.tex, manual/plugin_graph.pdf and parameter_view/parameters.xml, which should be restored (using git checkout) before creating a pull request.

The fact that latex cannot find the label in parameters.tex could mean several things. Two possibilities are a formatting error in one of the files used to generate parameters.tex (if you have accidentally run update_parameters.sh), or a problem with hyperref.

A couple of questions:

  • Does this problem persist on a completely fresh master branch on your local machine? (this would be particularly hard for us to troubleshoot, unless someone has had the same problem in the past)
  • If this works, what has changed on your failing branch relative to the master branch?

Best wishes,
Bob

Thank you for the response. I ran this on a fresh master branch, but I’m still getting the same error. Would you mind telling me a little more about the potential problem with hyperref?

It seems like the problem is with my computer setup. My colleague ran make manual.pdf on an updated version of ASPECT on a Mac with the OS Catalina 10.15.7 and succeeded. We have the same versions of pdflatex (pdfTeX 3.14159265-2.6-1.40.21 (TeX Live 2020)) and make (GNU Make 3.81). We also checked that we are running on the same type of shell (zsh). Do you have any suggestions on what else to check on my particular setup?

Best,
Karen

Karen: I don’t really know what’s going wrong. When you say “fresh master branch”, do you mean a directory you created from scratch via git clone so that there are really no other files in that directory other than those that git has put in there?

If so, I’m a bit at a loss. I know that compiling the manual works for a good number of people with no problems. I would have no idea what’s wrong on your machine, and don’t really know either how to find out. Maybe you could generate a tar file of everything under doc/ after you tried running make manual.pdf?

Best
W.

Hello Wolfgang,

Bob Myhill followed up with me and I just sent him the following response which should summarize everything I have tried. -Karen

Hi Bob,

Sorry for the delayed response. I have tried several approaches.

  1. I created a brand new git repository for ASPECT and tried compiling the manual. Unfortunately, I get the exact same error.

  2. I have also recompiled ASPECT and tried to run shell_simple_2d.prm for one time step. Once again, it seems that my system interprets the .prm files as dos files (see attached screenshot). If I run dos2unix on the .prm file I can run ASPECT.

  1. Since these efforts failed, I have decided to start over completely from scratch. I deleted my forked ASPECT repository and reforked it. I also updated my version of git to 2.29.2. After initiating my local git repository with git init I then did the following:

  1. I repeated number 2 from above and got the exact same error unfortunately.

In summary, I can be certain that it is not my git version, fork of ASPECT, or an issue with my master branch. Following Wolfgang’s suggestion, I have created a tar file of my doc directory, which can be downloaded here.

Thanks in advance for any new assistance.

Best,
Karen

Dear Karen,

Thank you for your files. Your copy of manual.tex is also in dos format (i.e. every line ends with CRLF rather than LF), which means that it can’t be read.

Rather than dos2unixing files until something works, it’s probably a good idea to work out what is going wrong. I suspect your version of git is configured to convert LF to CRLF (search for core.autocrlf at https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration).

  • To check that this is indeed the case: git config --list … I suspect core.autocrlf might be set to true.
  • To change this: git config --global core.autocrlf false
    (It is not clear to me exactly what the keyword value input will do on your system. It may be preferable to use this rather than false, but false should at least confirm what the problem is.)

You might need to reclone aspect again (just on your local machine; no need to refork).

Best wishes,
Bob

1 Like

Hi Bob,

You were correct. My core.autocrlf was set to true. Once I set the configuration to false and recloned aspect, I was able to compile the manual. Thank you so much for your help!

Best,
Karen

1 Like

Dear Karen,

You’re welcome, I’m glad you were able to fix the problem! Thank you for your patience while we hunted for the cause.

Best wishes,
Bob

1 Like

wow, I was not expecting this. Thanks a lot for your help, Bob.