Cross reference support (work in progress)

[jonasmalacofilho]

I had hoped to push something functional by Xmas, but I ended up working on the new server...

Still, I'm opening the pull request as is to get the tests to run (and to track the development).

• manual ids with \id{<id>}:
  • [x] spec/design
  • [x] parse
  • [x] apply to the structured document
  • [x] update the generators
  • [ ] enforce syntax rules at the parser and/or validator
• cross references with \ref[<optional type>]{<id>} and \rangeref[<optinal type>]{<id>}
  • [x] spec/design
  • [ ] parse
  • [ ] pass through the structuring
  • [ ] implement the resolution algorithm
  • [ ] html references
  • [ ] tex/pdf references
  • [ ] enforce syntax rules at the parser and/or validator
  • [ ] check ref resolution at the validator
• usage examples

[jonasmalacofilho]

Some additional details...

---

Reference types and generation:

• \ref type can be num, name or page
• page would refer: (pdf) page number; (html) section name (which is the equivalent to a page)
• references will be generated with hyperlinks on both html and pdf
• the default type depends on the element:
  • volumes and chapters: num + name
  • sections, sub-sections and sub-sub-sections: num only
  • figures and tables: num only
  • boxes: not sure yet
  • equations: num only
  • paragraphs and code blocks: page
• single cross reference examples:
  • \ref{volume.marketing} => Volume 3 (Communications and Marketing)
  • \ref{section.conclusion} => Section 4.7
  • \ref[page]{chapter.demand-analysis:figure.representation-of-study-area-for-analysis} => Estimating Demand with a Public Transport Model (web) or page 112 (pdf)
• examples of cross-referencing ranges:
  • \rangeref{chapter.demand-analysis}{chapter.traffic-impact-assessment} => Chapters 4 (Demand Analysis) to 8 (Traffic Impact Assessment)
  • \rangeref[num]{chapter.demand-analysis}{chapter.traffic-impact-assessment} => Chapters 4 to 8

---

Context based resolution:

• complete ids resolve trivially
• for the rest, we simply "fill in" automatically the missing contextual data from the place where the \ref appears
  • for example, \ref{section.conclusion} might resolve differently depending on the context
  • if it appears inside chapter 4, we will add the missing chapter info and end-up with chapter.demand-analysis:section.conclusion
• this is easy to implement
• actually resolving becomes trivial (with an extra 'manu' pass): we register all ids into a map during the structuring phase, and during a new resolve step we fill in the missing contextual data and resolve the reference immediately in O(1) time