Add printable design using Paged.js #62
Conversation
Removed 'color-scheme' and 'typeface' toggle buttons.
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Guidelines (I'm following)
Some drawbacks
Conflicts/Errors(in the process of loading a document using Paged.js.) It's very easy, if you are not careful, to get random rendering issues when you load\reload the paginated document. So you must be careful that all your scripts that modify the DOM and CSSOM have finalized before Paged.js starts to process the document. From Paged.js documentation:
So the solution for scripts is to load them before Paged.js; but there are also some other problematic elements: those that can be lazy loaded.
In conclusion, I think it's recommended not to use web-fonts and do not lazy-load images. Some tasks to consider
Other considerations
PR Tasks
(updated: wrong PDF attachment) |
ToC differences with default LaTeX.css, to mimic LaTeX default styles: - No padding for root ToC list. - First-level ToC sections in boldface style.
|
About line-height calculations (to fix the error) I made a mistake with the value of the line height (I forget to transform To explain the upcoming change (so that there is no doubt), I'm going to comment how line height is determined both in LaTeX and HTML (as far as I understand). In LaTeX, the line height is mainly determined by Approximately, the [defined-by-me]-ratio So "approximately^2" the method how line height is determined in LaTeX is: So,
(I usually use 1.3 and 1.6 resp) And the more natural way how line height is determined in HTML is (supposed So, assuming that the same units are used, equating both expressions for So, obviously (it's actually the same as above):
|
- New CSS class `toc-page-numbers` - Display ToC page numbers in `print.html` document
|
Finally, this is my proposal for the ToC (with page numbers). This is how it looks (left:Firefox, right:Brave, line-height still unfixed): The ToC must be manually written as for LaTeX.css without pagination. I have tried several options (the nested lists have been a headache), but I think this is the best compromise between "LaTeX resemblance" and "javascript usage". It has been "necessary" to add (using javascript) a container for the dotted-line, but the rest of the original ToC HTML code remains unchanged. Main Disavantages:
ToC layout differences
I think the only way to automatically mimic LaTeX style (if desired) is by using more javascript for size calculations (maybe it could be manually achieved with a set of custom CSS classes). |
|
List issues As it has been commented before, for ToC design I have tried to keep balance between "javascript code used" and "LaTeX features achieved". I would like to show some errors that may happen to lists while the document is been split (most of them for Chrome-based browsers). I thought this behavior was expected, and it was supposed you must use Some more of this situations can be added: it not only occurs with
I will add later some classes for Other possibility it would have been to use javascript to process all lists, transform them into one-level nesting lists, while the nesting level is represented through CSS classes. So a simpler list is obtained, with a more easy CSS customization (I suppose). It also be easier to use One more challenging error while splitting, occurs with default
For the moment, this particular Firefox error must also be manually fixed by the user: you must add |
|
Thank you so much for this PR @vihuna! I've had a look at your code and comments and I'm impressed with the work you've done here. Here are my thoughts:
if (location.hash) {
setTimeout(() => {
window.scrollTo(0, 0);
}, 0);
}to after: () => {
if (location.hash) {
const hash = location.hash;
const element = document.querySelector(hash);
if (element) {
element.scrollIntoView();
}
}
return ...
}
Going forward, I think that adjusting overflows would be the most important thing to do. Especially the scrolling code blocks require some text-wrapping. I would also force light mode by removing the More document font sizes would be nice, but I think that adding a "wider" version that fits more text on a page would also be quite useful (side notes will pose a challenge though -> maybe remove them entirely?). I would agree that removing the margin-top from the first paragraph (or heading) of each page would be good to keep the page layout consistent. I think that there is a lot that could be done (footnotes on its associated page, headers, etc.). I'm currently not in the position to do much work on this myself but I'm happy to review your work, comment it and merge it once it's ready. It just might take a while until I get to it. Again, thank you so much for your work on this! |
I agree.
I think is a very good solution, I have tested an it works. Thanks for this great improvement.
It's also needed for the ToC links: if not removed, the pages after the Image are not rendered and some of the ToC links will not work (Paged.js does not finish to render the document until the image is loaded).
I agree, specifically with complex lists.
It should be possible to do automatically with javascript the manual solution that I remarked previously. I would like to do it only for Firefox (and without user-agent identification), so a specific "firefox" option must be provided (in some way ...).
Me too. I want to finish two issues I was working on (I comment them later). I understand that you are referring to "automatic text-wrapping" with CSS (tell me if I'm wrong, I also prefer this way). I just want to note that LaTeX does not wrap text inside
Well, it's almost finished. Different page designs will be implemented through CSS named pages. My idea was to change the default I paused this because I was undecided about merge all
Unfortunately I think this is not possible. In PDF format, "internal hyperlinks" are not a special type of hyperlinks (special URL): internal links are made using "Link Annotation" objects, and external links using "URI Action" objects (screenshot with unpacked PDF, left Firefox, right Brave):
It seems Firefox-pdf always use the "URI Action" for all type of links (as a way to avoid confusion, this links can be removed before printing to pdf). Firefox external links work correctly. Also, WebKitGTK removes all links. I almost haven't tested WebKit (epiphany in Linux), it should be equivalent to Safari (I will try to test Safari printing on Windows).
I understand the advantages, and I see no problem for personal local usage (this user has already written the document using LaTeX.css). But it seems a more delicate question for a document on a public web host, that you want to allow printing (perhaps users doesn't know about LaTeX.css, they are not warned about it before arriving, using their favourite web browsers ...). Without any doubt, Chrome-based browsers are the recommended ones, and we must highlight it this way in the documentation (just as Paged.js does). This point should be discussed further.
I'm beginning to understand that you would like [if possible] an "out of the box" working (i.e., almost without user supervision). I think at this moment is far from possible, but some steps in this direction can be taken. The problem, and the reason because I choose the "all manual" way: I think it's more simple for the users to see the need for a page break at certain line/position in the document, instead of dealing with a page-break (introduced previously by LaTeX.css, not working properly for some reason, and users probably don't know how LaTeX.css inserts this breaks) that they must override and insert their custom one. Also, if you oversaturate the document with forced page-breaks and page-break-avoids, Paged.js may not work properly. Even LaTeX, by default, relies on the user judgment to verify if text in About the sidenotes, it's a feature I really like; and unfortunately, there are also other problematic elements. Let's give the sidenotes a chance for the moment, and we can decide about them later. I need to think more about all this.
I understand, thanks, I appreciate your support and your work on LaTeX.css. |
|
I have been working lately on three points:
(EDIT: it seems more effective to use |
|
More Pagedjs-Firefox issues (this doesn't affect the document rendering) Firefox users can get some errors with Pagedjs if they also use MathJax:
This is due to the "assistive MathML" feature used by MathJax. You can disable it in MathJax options: MathJax = {
options: {
menuOptions: {
settings: {
assistiveMml: false,
}
}
}
} |
Use a more flexible way to load Paged.js config: - Make `onloadPromises` not public: it can no longer be used to add additional user promises. Paged.js custom config must be done outside LatexCss. - Make LatexCss startup promise public, so the users can use it in their custom Paged.js settings. - Do not overwrite user config for Paged.js if it has been already provided. - `MathJax.startup` and `Prism.highlight` are now used to verify if MathJax and Prism are loaded, to avoid false positives. - Add log messages if Prism, MathJax, `removeImgLoading` and `toc-page-numbers` are detected. - Add fallback method example to Paged.js loading section
Do not force to use `id="top"` with `body`.
Remove the functions wrapping the promises `removeImageLoadingPromise` and `addTocNumbersPromise` (not necessary anymore).
`let` -> `const` for variables that are not going to be re-assigned
Using @vincentdoerig proposed solution: vincentdoerig#62 (comment)
The US letter page size will be implemented using CSS named pages. - Merged files: `print.css` + `print-A4.css` -> `style-paged.css` - Renamed files: - `print.html` -> `index-paged.html` - `latex-css-print.js` -> `latexcss-paged.js` - Modified the doc and code comments to reflect these changes in file names.
|
Before changes in a98dd41, Paged.js settings provided by users were overwritten by After the changes, user settings for Pagedjs are respected, and LatexCss.js provides a startup Promise (which includes MathJax and Prism promises, if they are used, among others), so responsibility lies with the users, if they want to change default Pagedjs + LatexCss settings. In 965364d the CSS "paged" files have been merged. |
|
I have already made some decisions and I have a more specific idea about the tasks in this PR (a task list has been added). Some comments:
|
- Use vite to build `latexcss-paged.js` script: used library mode to bundle the source files and built as an iife function - Evaluate `LatexCss` promises when Paged.js runs `PagedConfig.before` - Add `style-paged.css` to the package build - Add package command `preview`, in the root path
- Use `latex.now.sh` domain in code examples - Improve instructions of «Loading» section - Remove `defer` attribute in code examples
|
Deployment failed with the following error: |
|
Not much to say about the vite build config, the javascript modules are compiled in library mode, as an iife function. I have also added a "vite preview" command to config, in the base path. It has not been changed any of the Promises, only the way they are loaded (maybe that change goes unnoticed). Before these changes, the startup promises were evaluated when the old file This is quite important for Mathjax and Prism detection, for example. Before these changes, Mathjax and Prism scripts had to be executed before That means that a configuration like this will work properly <script src="latexcss-paged.js"></script>
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
<script id="MathJax-script" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>but you must be lucky with this other ones: <script id="MathJax-script" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
<script src="latexcss-paged.js"></script><script defer src="latexcss-paged.js"></script>
<script defer src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
<script defer id="MathJax-script" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>At this moment, I don't know the best solution to avoid that limitation (load Paged.js dynamically?, import it [the |
|
I have never used Vercel, but I suppose that it does some trick with the repo URL for the deployment of PR branches, what fails after you change |
Image from Paged.js was excesively large
Non-paged document footnotes are processed into CSS Paged Media footnotes to keep compatibility with non-paged LaTeX.css articles.
Transform the sidenotes from one or both margins into Paged Media footnotes, depending on the the sidenotes style choosen: `sidenotes-inner`, `sidenotes-outer` or none of them.
|
Some comments about CSS Paged Media footnotes implementation:
|
|
I appreciate the continuous effort and dedication you've shown, along with your patience on this PR. While I will not address each point individually, please know that I appreciate all the reasoned comments you've provided.
You are right, I appreciate your input and agree that creating a "plug-n-play" solution would go beyond the scope of this project. "All manual" should indeed be the way to go and we should mention this in the documentation that while it is almost straight-forward, it does require some work from the developer and should only be used on dynamic content with caution.
Smart!
This is indeed unfortunate. Let's hope that these bugs get fixed and we will hopefully be able to support more browser engines in the future!
Understood. From a print perspective this limitation isn't too bad since it's usually better to keep things consistent on one side (except maybe for two-sided books but don't get me started with that haha). What was your reasoning for sidenotes not being displayed by default?
This is a fair tradeoff but we should not make it too confusing. Creating (regular) sidenotes with a symbol instead of a number is not possible anymore, am I seeing this right?
I agree that this makes a lot of sense. (Versioning in the project in general is also something that has been on my mind for a while now...)
I appreciate you exploring the feasibility. I am totally fine with it "only" working in light mode.
The documentation you wrote seems to make it clear enough, no?
I also don't know what that was about, but as you mentioned it seems to be working again.
Seems to work great with the few examples I have tried:).
Since we both agree that this is not supposed to be an automatic solution, I believe it's acceptable to let the developer handle it. I'm still having some issues with page breaks (??). In your current version (32f1090), I am only seeing 13 out of the 14 total pages on Chrome (120.0.6099.234). I think it has to do with the indentation of parts of the Regarding the documentation, here are my two cents to what we need:
Feel free to implement things differently or we can discuss them here. I'd be happy to review again (and it shouldn't take this long anymore). Thank you! |
|
Thanks, I appreciate all your comments and indications. I will read and comment them carefully later. I'm only going to comment now the "last page missing" issue. I THINK (because I'm not able to reproduce it, Prism+Paged.js combination results in loos of some new line characters ("\n"), when Paged.js breaks the code block while pagination (with the rest of the document displayed correctly until the last page). I was aware about this issue while working on d2d2336 (this is one of the "individual issues" that took me the longest). In my opinion, Paged.js is responsible of this behaviour, because I verified that all newlines were there after the Prism processing, but I don't know how exactly happens. I have this link from Paged.js repo in my notes: Of course, Prism makes the HTML code more complicated, so makes Paged.js more likely to fail. I also have annotated this link from Prism repo (about "deleted newlines"): And I was "playing" with this code to patch this issue (I also have annotated that Prism removes the const preEl = document.getElementById("pre-id");
preEl.innerHTML = preEl.innerHTML.replaceAll(/\n/g, "--newline--");
Prism.hooks.add('after-highlight', function (env)
{
env.element.innerHTML = env.element.innerHTML.replaceAll(/--newline--/g, '<br />');
env.code = env.element.textContent;
});As I already have said before, I decided to leave this issue for later. Sometimes, Paged.js miscalculates the remaining space in the current page while paginating, so there is some overflowing content not displayed. Apparently, Paged.js has eaten some lines, but it's all there. I have not thought anything about that. And sometimes happens that Paged.js ends the document rendering prematurely, at the bottom of some page. In fact, it's similar to the previous case, where now Paged.js does not beak the pages anymore: the rest of the document is there, but it doesn't fit the page. I have verified that Paged.js fails to calculate the The only solution at this moment for this errors is a manual Finally, the point I'm most interested in: why I don't have this error? Yes, I'm working with an older Chromium version (117.0.5938.149), but I have also tested the latest available in Debian (121.0.6167.160-1~deb12u1) with the same result. I think this is because the "still non-fixed" relative units and also the font used for the preformatted text (I was awaiting until you had some time to comment about this). We should provide a Monospace font, verify the computed fonts, and throw a warning (popup?) if finally uses a fallback font, because the document will not be rendered like the author designed it, in this case. Tell me how we are going to do this (remote web font, or add another font to the repo ... and I just remembered that is And this also brings to my mind that there is some symbols ( |
|
«Last page missing» issue updates: I have been testing the page breaks inside I have finally come to the conclusion that the "problem" is effectively originated from the CSS code It seems the problem for the What appears to happen next is the same process as when some indivisible element does not fit the page: Paged.js would be trying to assign a I have also some doubts, while Paged.js is immersed in this process: the And, after all this, I have more questions: why are there no similar problems with the MathJax processed lines? (also with a lot of This is finally not very explanatory, but I think it's enough to "blame" Paged.js for the issue. We have some options to deal with it:
Update(24-03-2024): I'm now pretty sure Paged.js is causing this error, but I don't know the internal Paged.js issues (I don't want to comment more about this, but as final result, Paged.js fails to add the About unit testing: I'm familiar with jest+jsdom, but it's probably not very useful to test this issues with page breaks. Maybe e2e testing could be more useful¿? Until something is done about tests, some of this "manual examples" could be added to the repo. |
- `break-before-avoid`, `break-inside-avoid`, `break-after-avoid` to avoid breaks, - `break-before-page`, `break-after-page` to force breaks.
So it does not try to remove later what it doesn't exists
Because hyphenation was disabled, I increased "a little" the sidenotes width. So if you are not going to use any sidenote you'll probably want to decrease the margin width. The margins for no sidenotes are more natural. We can try to find a more balanced solution.
OK, I also didn't like it while I was writing it, it's confusing , I didn't want to close the door to some possible features.
There are two (or three) questions here, I'm not sure if it's clear.
I'm not sure it's clear enough. I must check again the loading method (after the "module" changes) and its documentation. Regarding the documentation:
Sure. I already was aware about this, I changed it for "paged layout" in commit 965364d. I Like both "LaTeX.css to PDF" and "Print-friendly documents".
This will be cool, but could have some work.
I thought also about this. The easiest method is to add an |
- Add top warning banner for non-Blink based browsers - The banner is added after Paged.js processing
- Use a base font size in absolute units
- Add Libertinus Mono and Latin Modern Mono for code snippets
- Switch off assistive MathML
- Replace unsupported symbols:
- U+2003 (EM SPACE) -> U+00A0 (NO-BREAK SPACE)
- U+21A9 (LEFTWARDS ARROW WITH HOOK) -> U+005E (CIRCUMFLEX ACCENT)
- U+25FE (BLACK MEDIUM SMALL SQUARE) -> `q.e.d` or U+2016 (DOUBLE
VERTICAL LINE)
Adjust some document font sizes for CSS styles `.font-size-10` and `.font-size-12`.
|
Banner and consistent rendering To allow consistent rendering across different platforms/environments, I have added the Mono fonts for Latin Modern and Libertinus. I have used the same versions of the fonts: v2.004 (2009) for Latin Modern and v7.020 (2020) for Libertinus. Some notes about Latin Modern (only otf format available): -> From "otf" to "ttf" Command: Output: -> From "otf" to "woff2" Command: Output: -> From "otf" to "woff" Command: Output: About the banner, finally I have realized (too late and by accident) that adding the banner after Paged.js has finalized (just like I have done it) is not a great idea: some elements can delay the rendering (like lazy loading fonts) and the banner appears after some seconds. Also some simple web browsers don't support some javascript functions used in Paged.js and you can get a blank page without any warning. Adding the banner before Paged.js will be a better option, if possible. Despite this, I decided to commit this changes, although I didn't finished the banner completely (I was going to allow multiple banners in the same modal box, and close all together), to be able to move forward. |
|
I have been doing some tests for the "consistent rendering" across different platforms/OS/DE, and I must say that it seems an utopia.
I have tried to solve similar issues in EPUB documents with poor results (from reader internal font-smooth options, to CSS For the moment, these results recommend to limit the use of Paged.js to local/personal environments but not to use it in a public web server. Tell me your opinion. |
|
Making a recap about the state of this PR Mi initial idea was: if Paged.js is quite solid with a LaTeX.css document, with this new feature you could (hit two birds with the same stone):
And, also important, implementing all this new feature "in/using the web browser". I also wanted to show all problems that I was finding along the way while exploring the possibilities, and I've tried to be cautious about the expectations (someone will say that I am always very pessimistic). But Paged.js is sincerely too much unstable, specially for technical/complex documents like those using LaTeX.css (with quite a few LaTeX+MathJax formulas, code blocks ...); and because the inconsistency across platforms, you have zero confidence that your document is going to be displayed correctly in a third-party browser. (I was hoping that since it was the same application, Chrome, those font-rendering inconsistencies would be quite unusual, or, better said, would rarely affect pagination). So, probably, "you are only going to use this feature at a developer/author level, to print the document to PDF". Well, I think there are quite better options to do this task (via conversion to LaTeX first), taking into account all that Paged.js issues I have found. So to be honest (and realistic), at this point I'm not convinced with this PR, and the "exploration days" end here: I already know enough about limitations across platforms and Paged.js instability; and things like " So, @vincentdoerig,if you still want to merge it, I can finalize the remaining most essential tasks. But I repeat my point of view: if "you are only going to use this feature to print the document to a PDF file", there are much better options to explore (even if you have to install some package in your OS). Sorry if this is a disappointment for you, but I need to be honest (regardless of the time spent on this PR); tell me your thoughts @vincentdoerig. |
Add "printable" design using Paged.js (WIP)