sillsdev / sillsdev/ptx2pdf

Discussion topic: flowing footnotes onto other pages

Open
#933 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
33
Forks
15
PR merge metrics
No merged PRs in 30d

Description

General topic / background.

The basic concept of a footnotes flowing onto another page was in TeX in the 1990s, maybe earlier. Fundamentally, however, we break/disable/ignore the internal (TeX-provided) mechanism in PTXprint.
The internal mechanism relies upon the careful estimation of space left on the page as text and other items are added to the page-list, before lay-up. We have, in one way or another, decided to turn it off and ignored it, not attempting to assign an appropriate size or scale for notes or other inserts. Constraints such as balancing columns rely on a more brute-force approach of re-flowing the entire page until the code accepts the results. By over-collecting input we slow down the code, but ensure that we don't under-fill a page.
Column notes are problematic for the internal mechanism in that they have no impact on the page space until the centre column is full.

Options

  1. Implement a mechanism to shave off lines of the final footnote, whatever its class, if the page doesn't fit (assuming it's multiple lines long). One drawback is that this solution preferentially pushes footnotes onto the next page, rather than body-text.

  2. Another option is to make a concerted effort to allow TeX to do a better job at properly estimating the page contents. The problem with this is that the re-flow of paragraphed notes is largely incompatible with this mechanism. However, do study bibles with long notes actually use paragraphed notes, or do they, for the reader's sake, use separate notes? Separate notes fit well with the normal TeX way of doing things. Column notes do not.

  3. A third option is to pick a particular note class which would be shaved, and put the shaving code into the 'make note box' code. This would allow the user to say "column references don't split, but "\f" notes do.

  4. The enhanced version of shaving is to attempt to shave all classes of note. Challenges with this involve some kind of optimisation of 3 or more variables, admittedly with only a few acceptable values.

Open questions

  • Is packing more main text on the page an less of the last footnote a big enough problem that it's worth trying approach 2?
  • Is the best approach rewriting the code to try footnote-shaving only as a 'last resort' option in some particular circumstance? When?
  • Is a mixed-method the best approach - Allow the internal-mechanism to handle separate notes, and the brute-force method for paragraphed notes?
  • Shaving footnotes only (currently) works on the last note on the page. What if there are long textual notes and occasional, and unsplittable xrefs?

Current state of work-in-progress

  • Shave footnotes with a single breakpoint [proven]
  • No shave of footnotes with no breakpoints [proven]
  • Handle multiple breakpoints [done]
  • Generate multiple breakpoints [done]
  • Special handling of last footnote to allow all linebreaks as breakpoints [working]
  • Refuse to shave < \LastNoteShaveMin lines onto the next page [done]
  • Refuse to shave if doing so will leave < \LastNoteShaveStay [done]
  • Refuse to shave last note if it's < \LastNoteShaveShortest lines [TODO]
Un-broken notes

image
-- nxt page
image

A break at \fp

image
-- nxt page
image

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files, tests, or entry points are named. Start by reviewing the existing footnote-shaving work and the listed open questions, then determine which approach and note classes are in scope. Done should include a settled implementation direction and resolution of the remaining TODO for the shortest last note, with validation of the listed breakpoint cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
tex
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.