I'm currently working on a documentation for a big project that is an extension of an existing one, and I'm looking for the solution of a problem that can be troublesome for the sustainability of the code.

For the previous project, we had comments inside the code such as "// Equation 26 in annexe B of Documentation-VersionX" which allowed us to check the theory behind functions inside the code, and to verify if the function corresponded to the equation. However, as you can imagine, things get troublesome if we insert a new equation in the model as all equation after this one will not be referenced correctly afterwards (old references to "Equation 26" would need to become "Equation 27").

I've been thinking about a way to create a refrence for each equation that would be independant of other equations, but it wouldn't be good to read a documentation and have equation label/numbers not following the classic order. This means that the reference in the documentation has to be like before ("Equation 17" needs to be the 17th equation in the paper), so I need to fix an unchanging-number for each equation inside the LaTeX code which is referenced inside the JAVA code of the project. This unchanging-reference could then be paired with the "true" reference for this equation inside the PDF.

Parsing Java file and changing unchanging references to a pair of (unchanging reference, PDF number reference) is something that I can manage, but I don't know how to extract automatically those PDF references that are generated by LaTeX, and pair them with their unchanging references inside an output file.

I'm sorry if this question isn't very clear, I had trouble finding similar problems on SE or Google. I don't have a lot of experience with advanced LaTeX tasks like this, and the only way to do this outside LaTeX would be to parse the .tex file for each equation label, order them in the pdf order, and parse the Java code to insert the true PDF reference. This way seems kinda barbaric, so I'm looking for another way to do this if possible.

Edit : To clarify my question : I would like to find a way to create unchanging references to my equation (like labels), and pair them with their actual number in the PDF (example : Equation 25, which is referenced a Q_eval_2 in the .tex) in an output file. With this output file I could manage to create, artificially, the cross-referencing that I'm looking for.

  • 2
    It seems like you've hard-coded the references then, instead of using the xr package together with proper \labels and \refs, correct?
    – Werner
    Commented Nov 7, 2019 at 15:47
  • Currently, the equations are labeled inside the .tex, so that they can be referenced to later when needed. They are in a equation block. Hard-coding the references is what i would like to do but it wouldn't allow me to know the "number" of the equation in the PDF, which is needed for the cross-refrence between PDF and the project code. As there is no other .tex file in this documentation, the xr package hasn't been used here.
    – Nicinic
    Commented Nov 7, 2019 at 16:42
  • 1
    Sure. You can write the equation numbers in a separate file if you wanted to that can then be used (extracted) by some other program. The former is a good question on this site. The latter (extraction for use in some other program and/or PDF) is not. Can you clarify your question knowing all of this information?
    – Werner
    Commented Nov 7, 2019 at 19:12
  • 1
    Welcome to tex.sx. It might be possible to make use of the information written out in the ,aux file, associating a label with the assigned object number. Commented Nov 7, 2019 at 20:01
  • Seems like the .aux file can be used for this, as it contains both the label, as well as the actual number of the equation (like this : \newlabel{testEQ}{{4.1}{14}}). With this, i can easily parse, and thus, create this cross-referencing without any problem. Thank you both for your answers !
    – Nicinic
    Commented Nov 7, 2019 at 21:34

1 Answer 1


The .aux file produced by a successful LaTeX run contains the information needed to resolve cross references -- both the label and the number or other ID of the target object. For example, an entry for an equation might be


where 4.1 is the equation number and 14 is the page on which it appears.

Assigning "meaningful" labels rather than using the initial numbers assigned to the objects will provide a lasting and secure association that should be easy to maintain in both the commented code and the documentation. An example of such a "meaningful" association might be

  E = mC^{2}

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .