diff --git a/docs/Help/Technical-Notes/Page-Formatting/appearance-system-css.md b/docs/Help/Technical-Notes/Page-Formatting/appearance-system-css.md index 95622e4..e7cfc90 100644 --- a/docs/Help/Technical-Notes/Page-Formatting/appearance-system-css.md +++ b/docs/Help/Technical-Notes/Page-Formatting/appearance-system-css.md @@ -62,7 +62,7 @@ The HTML page then applies these stylesheets in this order (last wins, all other A challenge in modern Bloom is that there are a number of things that each influence the final display of a page. These things may even be wanting opposite things to happen. What happens if the Book Settings Dialog is used to turn something on, but a custom css is used to turn it off? Who wins? -Since ultimately CSS is involved, the answer is complicated by CSS specificity rules. But given the same specificity, here is the order of precendance for the various sources ( `>>` here means “has precendence over”): +Since ultimately CSS is involved, the answer is complicated by CSS specificity rules. But given the same specificity, here is the order of precedence for the various sources ( `>>` here means “has precedence over”): :::note @@ -74,7 +74,7 @@ xmatter HTML >> customBookStyles.css >> xmatter.json >> brand -Why is xMatter pug the ultimate winner? This is because, if an xMatter doesn’t have an HTML elemetn for something, it can’t be CSS’ed or JSON’ed into existence. +Why is xMatter pug the ultimate winner? This is because, if an xMatter doesn’t have an HTML element for something, it can’t be CSS’ed or JSON’ed into existence. Notice that Theme’s position in the list. Not only is it last, but actually any property that appears in Book Settings will win over that described in the Theme, unless CSS specificity rules cause it to overcome the Book Settings. @@ -101,7 +101,7 @@ If you cannot get what you need using the Book Settings UI or by choosing a them -If it doesn’t already exist, create a `customBookStyles.css` in the root of the book folder. **Use an editor that understands CSS** will show you any errors. We highly recommend [Visual Studio Code](https://code.visualstudio.com/download) (it is free). The basic template is: +If it doesn’t already exist, create a `customBookStyles.css` in the root of the book folder. **Use an editor that understands CSS** will show you any errors. We highly recommend [Visual Studio Code](https://code.visualstudio.com/download) (it is free). The basic template is: ```css @@ -203,7 +203,7 @@ For a long time, highly technical Bloom users have been able to go “under the | --multilingual-editable-vertical-gap | | | The space between the different language sections of each block when Bloom is configured to show each block of text in more than one language. [default is _10px_] | 6.0 | | | --page-background-color | | | _background-color_ for the full content of all pages. [default is _white]_ | 6.0 | | | --page-gutter | | | additional inner margin for pages of a book. [default is _0mm_ since most Bloom books are too small to need a gutter, or are published as e-books that inherently don’t need a gutter] | 6.0 | | -| --page-margin | | | margin for all pages. Aspects can be overriden by the more specific --page-margin-* properties. | 6.0 | | +| --page-margin | | | margin for all pages. Aspects can be overriden by the more specific --page-margin-* and —cover-margin-* properties. | 6.0 | | | --page-margin-bottom | | | _padding-bottom_ for inner pages, i.e., not outside cover pages, but including inside cover pages. [default is _12mm_] | 6.0 | | | --page-margin-left | | | basic _padding-left_ for all pages. It is added to **--page-gutter** for left-side pages. Also used for _padding-right_ for pages which are inherently symmetrical left vs right. These include outside cover pages, calendar pages, Device16x9… sized pages, etc. [default is _12mm_] | 6.0 | | | --page-margin-right | | | basic _padding-right_ for all pages. It is added to **--page-gutter** for right-side pages. [default is _12mm_] | 6.0 | | @@ -292,3 +292,60 @@ For a long time, highly technical Bloom users have been able to go “under the | .bloom-page[class*="Landscape"] | Apply only to Landscape layouts | | .bloom-page[class*="Portrait"] | Apply only to Portrait layouts | + +## Migrating old custom CSS {#93cc6fe2fca8440094dff51b91ebfe60} + + +If you have existing customBookStyles.css files, here are some of the main considerations for moving to the Appearance system. First, just try opening your book in Bloom 6.0 (or later). Go to the book settings dialog and see whether the page theme is Default, Legacy (Bloom 5.6), or something else. If it’s something other than Legacy (Bloom 5.6), you’re lucky… we already did the migration for you. It would be good to check that you like the results and see if there’s anything you want to tweak, but you shouldn’t need to do any more, unless you want to clean up padding, as described in the release notes. + + +If you see “Legacy 5.6” then your book is, for the moment, stuck in the old days. It is using custom CSS that’s not compatible with the Appearance system. Some things in the Book Settings dialog are already disabled, and it’s likely that more new capabilities won’t work over time. We would encourage you to switch over. + + +The first thing to try is just to change the theme to Default. (You could also try some of the others.) This will disable your custom CSS and give you one of the new layouts. One of them might be close enough, especially if you make use of the new Book Settings! Then you can just discard your custom CSS. (Or if you or colleagues are still using 5.6 to work on this book, you may want to keep it until 6.0 moves from Beta to Release.) + + +If you still want custom CSS, we encourage you to see what you can do by setting the variables described above. If you want to do something that can’t be done with them, we’d like to know about it… maybe we can add some more variables. + + +In particular, books get locked into the legacy theme mainly if their customBookStyles.css sets the position and size of the margin box. You can replace such rules using the Appearance system… usually much more easily. For example, if you want just 2mm of margin around your page, and 5mm more on the bottom to show page numbers, in the old system you’d need something like + + +```css +.Device16x9Portrait .marginBox { + top: 2mm; + left: 2mm; + width: ?mm; /* width of a Device16x9 portrait page minus 4mm */ + height: ?mm; /* height of a Device16x9 portrait page minus 9mm */ +} +/* and maybe */ +.Device16x9Portrait.titlePage, +.Device16x9Portrait.creditgsPage { + height: ?mm; /* height of a Device16x9 portrait page minus 4mm, not leaving room for page number */ +} +.A5Portrait .marginBox { + /* ...needs different width and height for a different page size */ +} + +/* And similarly for any other page sizes you care about */ +``` + + +In the Appearance system, you can just do + + +```css +.bloom-page { + --page-margin: 2mm; + --pageNumber-extra-height: 5mm; +} + +/* if you want a bigger margin on A4 you can do it, but the above will work for all sizes where you want 2mm. */ +``` + + +You could also set `--page-margin-bottom` to 7mm, but the above is better: it will do the right thing on pages that don’t have numbers and if you use book settings to turn off page numbers. + + +Other things like padding don’t _have_ to be changed; but see [Bloom 6.0 Beta Release Notes](/release-notes-6-0) for how padding has been improved and may make awkward ways of doing things unnecessary. The more you can do with the documented variables, the better your chances for compatibility with future Bloom versions and features. + diff --git a/docs/Help/Technical-Notes/Page-Formatting/appearance-system.md b/docs/Help/Technical-Notes/Page-Formatting/appearance-system.md index f4a5058..f8b45bb 100644 --- a/docs/Help/Technical-Notes/Page-Formatting/appearance-system.md +++ b/docs/Help/Technical-Notes/Page-Formatting/appearance-system.md @@ -60,7 +60,7 @@ Bloom version 6.0 introduces a new page styling system that we’re calling “A - Add Book Settings defaults to the Collection Settings, so that you can have all the books use the same themes and other settings - Individual books will be able to override the Collection Settings -# The migration from the old to the new system {#d997fa04c2bf494db0f705489a994f2e} +## The migration from the old to the new system {#d997fa04c2bf494db0f705489a994f2e} If a book is “saveable”, Bloom 6.0 will migrate it to the new system. It will do this in a way that will allow the book to keep working in older Blooms, Bloom Readers, and BloomPUB Viewers. @@ -89,7 +89,7 @@ The migration has these steps: 2. Otherwise, if Bloom recognizes the contents of that stylesheet, it will add a pre-prepared `customBookStyles2.css` and `appearance.json.` We intend to prepare these automatic migrations for some of the most commonly used `customBookStyles.css` found on BloomLibrary.org. 3. Otherwise, if the book has custom CSS that is compatible with the Appearance system, it will continue to be used in addition to the “Default” theme. -4. Otherwise, if the book has a custom CSS that is incompatible with the Appearance system, Bloom will assign the book to the “Legacy 5.6” theme, and use the custom CSS in addition to the legacy theme. The intended result is the book should look the same. If you later use the Book Settings dialog to change to a modern theme, Bloom will start ignoring the incompatible `customBookStyles.css` and offer to delete it. It will then look for a file named `customBookStyles2.css` in case you really need to change something that cannot be done with themes or customizing `appearance.json`. +4. Otherwise, if the book has a custom CSS that is incompatible with the Appearance system, Bloom will assign the book to the “Legacy 5.6” theme, and use the custom CSS in addition to the legacy theme. The intended result is the book should look the same. If you later use the Book Settings dialog to change to a modern theme, Bloom will start ignoring the incompatible `customBookStyles.css` and offer to delete it. It will keep checking customBookStyles.css and start using it again if you fix it to be compatible; see [Create Appearance-compatible custom CSS and Themes](/appearance-system-css). (You CAN also make or tweak your own customBookStyles2.css, but we don’t recommend it. That name is meant for custom CSS that is output by our migration system. Your changes might even get overwritten if at some point we decide we need to repair an automatic migration.) ![](./appearance-system.2c87f19f-c117-45f0-b177-57c0f7f0c031.png) @@ -100,8 +100,5 @@ The migration has these steps: There are now three levels of customization: 1. Use the new “Book Settings” UI to choose a theme. -2. Use the new “Book Settings” UI to choose a theme to set a small number of other properties, such as margins. -3. Create a customBookStyles.css file that uses the new properties. For this, see: - -[Create Appearance-compatible custom CSS and Themes](/appearance-system-css) - +2. Use the new “Book Settings” UI to choose a theme and set a small number of other properties, such as margins. +3. Create a customBookStyles.css file that uses the new properties. For this, see [Create Appearance-compatible custom CSS and Themes](/appearance-system-css). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/inserting-special-characters.d7d0877f-a7b0-4a45-b482-ef820ae88de6.gif b/i18n/es/docusaurus-plugin-content-docs/current/inserting-special-characters.d7d0877f-a7b0-4a45-b482-ef820ae88de6.gif index 686afdf..e3cc4b5 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/inserting-special-characters.d7d0877f-a7b0-4a45-b482-ef820ae88de6.gif +++ b/i18n/es/docusaurus-plugin-content-docs/current/inserting-special-characters.d7d0877f-a7b0-4a45-b482-ef820ae88de6.gif @@ -5,7 +5,7 @@ - +