diff options
author | Karl Berry <karl@freefriends.org> | 2023-12-16 20:49:07 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-12-16 20:49:07 +0000 |
commit | 54ebd4351ac431d68b117e0de5f94dff8b6edc75 (patch) | |
tree | 56da3107674acb4b36b588aeafdd093d0d9ab626 /Master/texmf-dist/doc/latex | |
parent | 1f2061abaa3de9858dc3d8a953ce4e2d515e7326 (diff) |
responsive (16dec23)
git-svn-id: svn://tug.org/texlive/trunk@69147 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r-- | Master/texmf-dist/doc/latex/responsive/README | 37 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/responsive/responsive-doc.bib | 91 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/responsive/responsive-doc.pdf | bin | 0 -> 77546 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/responsive/responsive-doc.tex | 543 |
4 files changed, 671 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/responsive/README b/Master/texmf-dist/doc/latex/responsive/README new file mode 100644 index 00000000000..dc2953cb549 --- /dev/null +++ b/Master/texmf-dist/doc/latex/responsive/README @@ -0,0 +1,37 @@ +The Responsive Package + +Version 0.1 + +Change font sizes and other typographic details in LaTeX documents depending on +the page dimensions. + +The Responsive package for LaTeX enables dynamic adjustment of document +elements for various output formats and devices. Key features include: + +- Font Size Adjustment: Set the font size to achieve an average number of + characters per line, enabling suitable font size selection for various sizes + of page formats or devices such as tablets and e-book readers. + +- Typographic Scales: Choose from predefined or define custom typographic + scales using options such as number and ratio. + +- Media Queries: Test document properties using media queries, allowing + conditional execution of code based on test results. + +- Line Spacing Control: adjust line spacing determining the x-height percentage + for enhanced readability. + +Copyright: 2023-2023 Michal Hoftich + +This work may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3 +of this license or (at your option) any later version. +The latest version of this license is in + http://www.latex-project.org/lppl.txt +and version 1.3 or later is part of all distributions of LaTeX +version 2005/12/01 or later. + +This work has the LPPL maintenance status `maintained'. + +The Current Maintainer of this work is Michal Hoftich. + diff --git a/Master/texmf-dist/doc/latex/responsive/responsive-doc.bib b/Master/texmf-dist/doc/latex/responsive/responsive-doc.bib new file mode 100644 index 00000000000..6c2cea1902e --- /dev/null +++ b/Master/texmf-dist/doc/latex/responsive/responsive-doc.bib @@ -0,0 +1,91 @@ +@manual{responsive, + title = {The Responsive package}, + author = {Hoftich, Michal}, + url = {https://github.com/michal-h21/responsive-latex}, + urldate = {2023-03-30}, + date = {2023-03-28}, +} + +@manual{rmodepdf, + title = {Rmodepdf}, + author = {Hoftich, Michal}, + url = {https://github.com/michal-h21/rmodepdf}, + urldate = {2023-03-30}, + date = {2023-03-28}, +} +@manual{rdrview, + title = {Rdrview}, + author = {Ernesto Fernández}, + url = {https://github.com/eafer/rdrview}, + urldate = {2023-03-30}, + date = {2023-03-28}, +} +@manual{luavlna, + title = {The Luavlna package}, + subtitle = {Prevent line breaks after single letter words, units, or academic titles}, + author = {Hoftich, Michal}, + url = {https://ctan.org/pkg/luavlna}, + urldate = {2023-03-30}, + date = {2023-03-28}, + version = {0.1k}, +} + +@manual{linebreaker, + title = {The Linebreaker package}, + subtitle = {Prevent overflow boxes with LuaLaTeX}, + author = {Hoftich, Michal}, + url = {https://ctan.org/pkg/linebreaker}, + urldate = {2023-03-30}, + date = {2023-03-21}, + version = {0.1c}, +} + +@manual{lua-widow-control, + title = {The Lua-widow-control package}, + subtitle = {Automatically remove widows and orphans from any document}, + author = {Chernoff, Max}, + url = {https://ctan.org/pkg/lua-widow-control}, + urldate = {2023-03-30}, + date = {2022-11-22}, + version = {3.0.0}, +} + +@article{chernoff, + doi = {10.5300/2022-1-4/49}, + author = {Chernoff, Max}, + title = {Automatically Removing Widows and Orphans with lua-widow-control}, + journal = {Zpravodaj Československého sdružení uživatelů TeXu}, + volume = {32}, + number = {1}, + pages = {49-76}, + issn = {1211-6661}, + year = {2022}, + url = {https://dml.cz/handle/10338.dmlcz/151108} +} + +@manual{luaxml, + title = {The Luaxml package}, + subtitle = {Lua library for reading and serialising XML files}, + author = {Hoftich, Michal}, + url = {https://ctan.org/pkg/luaxml}, + urldate = {2023-03-30}, + date = {2021-10-06}, + version = {0.1q}, +} + +@online{mortensen, + title = {The Typographic Scale}, + author = {Spencer Mortensen}, + year = {2011}, + url = {https://spencermortensen.com/articles/typographic-scale/}, + urldate = {2023-03-30}, +} + +@article{cavazza, + title = {Modern CSS Techniques To Improve Legibility}, + author = {Edoardo Cavazza}, + journal = {Smashing Magazine}, + date = {2020-07-22}, + url = {https://www.smashingmagazine.com/2020/07/css-techniques-legibility/}, + urldate = {2023-03-30}, +} diff --git a/Master/texmf-dist/doc/latex/responsive/responsive-doc.pdf b/Master/texmf-dist/doc/latex/responsive/responsive-doc.pdf Binary files differnew file mode 100644 index 00000000000..1e7245c04f1 --- /dev/null +++ b/Master/texmf-dist/doc/latex/responsive/responsive-doc.pdf diff --git a/Master/texmf-dist/doc/latex/responsive/responsive-doc.tex b/Master/texmf-dist/doc/latex/responsive/responsive-doc.tex new file mode 100644 index 00000000000..4272397e3e8 --- /dev/null +++ b/Master/texmf-dist/doc/latex/responsive/responsive-doc.tex @@ -0,0 +1,543 @@ +\documentclass{ltxdoc} +\newcommand\authormail[1]{\footnote{\textless\url{#1}\textgreater}} +\ifdefined\HCode + \renewcommand\authormail[1]{\space\textless\Link[#1]{}{}#1\EndLink\textgreater} +\fi + +\ifdefined\gitdate\else + \def\gitdate{\today} + \def\version{devel} +\fi + + + +% \usepackage[noautomatic]{responsive} +\usepackage[]{responsive} +\usepackage{linebreaker} +\usepackage{caption} +\usepackage{subcaption} +\usepackage{graphicx} +\usepackage{microtype} +\usepackage{longtable} +\usepackage{booktabs} +\usepackage[style=iso-authoryear]{biblatex} +\addbibresource{responsive-doc.bib} +\newenvironment{changelog}{\longtable{@{} l p{30em}}}{\endlongtable} +\newcommand\change[2]{#1 & #2\\} +\ifdefined\HCode + % I want to convert parts of the document to images, + % so I need to use Type 1 fonts for the correct conversion with Dvisvgm + \usepackage{ebgaramond} +\else +\usepackage{fontspec} +\setmainfont{EB Garamond}[Numbers=OldStyle] +\setmonofont{Inconsolatazi4-Regular.otf}[Scale=MatchLowercase] +\fi + +\newcommand\StartDescribe[1]{% + \par\medskip\noindent\DescribeMacro#1 +} +\usepackage{lipsum} +\title{The Responsive Package} +\author{Michal Hoftich\authormail{michal.h21@gmail.com}} +\date{Version \version, \gitdate} +\NewDocElement[macrolike = false , +toplevel = false, +idxtype += key, +idxgroup = Package keys, +% printtype = \textit{key} +]{Key}{key} + +\newcommand\printsize[1]{\csname #1\endcsname\par\noindent Sample\par} +\newcommand\showscale[2][.5\textwidth]{% + \noindent\fbox{% + \begin{minipage}{#1} + \ResponsiveSetup{#2} + \setsizes[34]{25} + \printsize{huge} + \printsize{LARGE} + \printsize{Large} + \printsize{large} + \hrule + \printsize{normalsize} + \hrule + \printsize{small} + \printsize{footnotesize} + \end{minipage} + } + \ifx\relax#2\relax Default parameters\else\texttt{#2}\fi\hfill\null +} +\makeindex + +\begin{document} +\maketitle +\begin{abstract} +Responsive design aims to display text and other design elements well on +variety of outputs, including electronic devices or various paper sizes. +It originated on the Web, where it uses Cascading Style Sheets to change +design elements. + +This package tries to achieve similar result with \LaTeX. The main aim is to +support output of multiple editions of one document with +readable font sizes regardless of the physical size of the produced PDF, +from smartphones or e-ink readers to printed A4 pages. +\end{abstract} + +\clearpage + +\tableofcontents + +\section{Introduction} + +This package aims to facilitate the creation of documents for multiple output +formats, such as various page sizes, e-book readers, or even mobile phones. + +One of the issues that needs to be addressed is setting the correct font size +for readability. The default font size in LaTeX is 10 points, regardless of the +page size. This is an appropriate font size for A5 format pages. For A4 format, +the font size should be larger, while it may be smaller for smaller displays of +e-readers and mobile phones. Similarly, we can adjust the line spacing, which +also affects text readability depending on the font size and page size. + +Web browsers face a similar problem as they must display text on both large PC +monitors and smaller displays of laptops, tablets, and mobile phones. The +solution they use is called \textit{responsive design}. + +Responsive design is a method of web design that allows flexible and dynamic +adaptation of the appearance and layout of page content to different display +devices. One of the key elements of responsive design is a flexible structure +that enables adjusting the size of elements on the page to the display device. + +Another important element is media queries. These allow defining rules based on +the properties of the display device, such as screen width and height or output +type (paper, display). Thanks to these rules, the same page code can be +well-displayed on both large monitors and mobile devices or when printing. + +The Responsive package is inspired by these principles. Its main function +is to set the font size based on the page size and the approximate number of +characters that should fit on the page (see figure~\ref{fig:example}). It also adjusts the typographic scale +(influencing font size, for example, in headings or footnotes), line height, +and supports a simple version of media queries. + + +\section{Features} + + +\subsection{Fitting Font Size to the Page Size} + +Regardless of the width of the page, there is a certain range of the number of +characters that should be displayed on average per line of text to ensure good +readability. With a larger number of characters, the reader may have difficulty +quickly moving to the next line, while shorter lines may lead to skipping +lines. + +The Responsive package automatically sets the width of the text to a chosen number of characters. +Figure~\ref{fig:example} shows a difference in the font size in two +different text widths. + + +\begin{figure}[htbp] + \caption{Example of changing font size based on the width of the text block:}\label{fig:example} +\begin{subfigure}[t]{0.45\textwidth} + \centering +\fbox{% +\begin{minipage}{4cm} +\ResponsiveSetup{} +\setsizes{} + +\lipsum[1] + +\end{minipage}} +\caption{Text width 4\,cm} +\end{subfigure} +% \hfill +\begin{subfigure}[t]{0.45\textwidth} + \centering +\fbox{% +\begin{minipage}{6cm} +\ResponsiveSetup{} +\setsizes{} + +% \lipsum[1] +Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit, +vestibulum ut, placerat ac, adipiscing vitae, felis. Curabitur dictum gravida +mauris. Nam arcu libero, nonummy eget, consectetuer id, vulputate a, +magna. Donec vehicula augue eu neque. Pellentesque habitant morbi +tristique senectus et netus et malesuada fames ac turpis egestas. Mauris +ut leo. Cras viverra metus rhoncus sem. Nulla et lectus vestibulum urna +fringilla ultrices. Phasellus eu tellus sit amet tortor gravida placerat. Integer +sapien est, iaculis in, pretium quis, viverra ac, nunc. + +\end{minipage}} +\caption{Text width 6\,cm} +\end{subfigure} +\end{figure} + + +\subsection{Typographic Scale} + +The typographic scale is a set of predetermined font sizes used to establish a +consistent visual style for a document or website. These sizes are typically +expressed in point units and progressively increase or decrease by a specific +interval along the scale. + +A typographic scale may include sizes for headings, footnotes, and body text. +Proper use of a typographic scale helps create a visual hierarchy that enhances +the readability and aesthetic appeal of the text. + +In \LaTeX, the typographic scale is accessible through commands such as \verb|\large|, +\verb|\huge|, or \verb|\scriptsize|. Each of these commands is one interval +away from the previous size. + +I drew inspiration from Spencer Mortensen's article (\citeyear{mortensen}), which defines several +different typographic scales and provides a method for easily creating +additional scales. +The default scale in the Responsive package, +which closely aligns with the scale used in \LaTeX, is referred to as \verb|tetratonic|. +The package also offers additional scales described in the +article, such as the golden scale based on the golden ratio. +See Figure~\ref{fig:scale} for differences between the default scale and scale based on the +golden ratio. + +The Responsive package includes several predefined typographic scales, but you +can also define your own. All scales are defined using the options +\verb|number| and \verb|ratio|, specifying how many steps (\verb|number|) the +font size increases by the size of \verb|ratio|. For example scale with \verb|number| of 2 +and \verb|ratio| of 5, will double the font size over 5 steps. +Table~\ref{tbl:scales} lists all predefined scales. + +\begin{table}[htbp] + \centering + \begin{tabular}{l l l} + \toprule + name & number & ratio\\ + \midrule + heptatonic & 7 & 2\\ + pentatonic & 5 & 2\\ + tetratonic & 4 & 2\\ + tritonic & 3 & 2\\ + golden & 2 & 1.618\\\bottomrule + \end{tabular} + \caption{Predefined typographic scales}\label{tbl:scales} +\end{table} + + +\begin{figure}[htbp] + \caption{Sample of Typographic Scales (the default font size is highlighted with lines)}\label{fig:scale} + \begin{subfigure}[b]{0.45\textwidth} +\fbox{% +\begin{minipage}{5cm} +\setsizes{45} + +\showscale{} + +\end{minipage}} +\caption{Default scale} +\end{subfigure} +\begin{subfigure}[b]{0.45\textwidth} +% \begin{verbatim} +% \ResponsiveSetup{scale=golden} +% \end{verbatim} +\fbox{% +\begin{minipage}{5cm} +% \ResponsiveSetup{scale=golden} +\setsizes{45} + +\showscale{scale=golden} + +\end{minipage}} +\caption{Golden ratio scale} +\end{subfigure} +\end{figure} +% % https://spencermortensen.com/articles/typographic-scale/ + + + +% \showscale{} +% \showscale{scale=heptatonic} +% \showscale{scale=tritonic} +% \showscale{scale=golden} +% \showscale{scale=none,ratio=1.3,number=2} + +\subsection{Line height} + +In the default settings of \LaTeX, the line spacing is set to the font size +multiplied by a factor of 1.2. For different fonts and page sizes, a different +line spacing may be appropriate. Similarly, distinct values may be suitable for +the printed and electronic versions of the document. + +The Responsive package provides two options which allows you to change the line spacing +(Figure~\ref{fig:lineratio}). + +First is the \verb|lineratio| option, which bases the line height +on the ratio between x-height of the current font and the desired height. +I've found this method in article by Edoardo Cavazza in the \textit{Smashing Magazine}~(\citeyear{cavazza}). +The value of the \verb|lineratio| option determines what percentage of the total line +height is the \verb|x-height|. The higher this value, the lower the line will be. For +different fonts, the same ratio may lead to different line heights because each +font has a different \verb|x-height| value. The appropriate lineratio size needs to be +determined experimentally. The default value should roughly correspond to a +line height of 1.2, the default in \LaTeX. + +Another option is \verb|lineheight|, which +is similar to the CSS property \verb|line-height|. Using it, we can choose the +line height as a multiple of the font size. + + + + +\begin{figure}[htbp] + \caption{Changing the line spacing by adjusting the value of \texttt{lineratio}.}\label{fig:lineratio} + \begin{subfigure}[b]{0.45\textwidth} +\fbox{% +\begin{minipage}{5cm} +\ResponsiveSetup{lineratio=38} +\setsizes{65} + +\lipsum[1] + +\end{minipage}} +\caption{lineratio=38} +\end{subfigure} +\begin{subfigure}[b]{0.45\textwidth} +\fbox{% +\begin{minipage}{5cm} +\ResponsiveSetup{lineratio=34} +\setsizes{65} + +\lipsum[1] + +\end{minipage}} +\caption{lineratio=34} +\end{subfigure} +\end{figure} + +% https://www.smashingmagazine.com/2020/07/css-techniques-legibility/ + +\subsection{Media Queries} + +Media queries are a technique that allows web developers to dynamically adapt +the appearance and behavior of websites based on various device properties, +such as screen width and height, device orientation, color support, and more. +Thanks to these conditions, responsive and flexible websites can be created +that automatically adjust to different types and sizes of devices on which they +are displayed. + +How can this technique be useful for \LaTeX\ package authors? They could, for +example, set the font size, line spacing, and other elements for specific page +dimensions. Once the user chooses the page size based on the device size for +which they want to compile the document, these elements are automatically +adjusted. For instance, a package author could define that if the width of the +text block is smaller than a certain dimension, fewer characters will be +displayed on each line compared to longer lines (Figure~\ref{fig:mediaquery}). + +The media query used for this figure looks like this: + +\begin{verbatim} +\mediaquery{max-textwidth=4cm} +{\ResponsiveSetup{lineratio=38}\setsizes{45}} +\ResponsiveSetup{lineratio=34}\setsizes{60}} +\end{verbatim} + +This media query defines that if the width of the text is smaller than or equal to 4 cm, a +smaller number of characters will be displayed per line to prevent the font +from being too small and difficult to read. Additionally, a smaller line +spacing will be applied. + + + +\newcommand\mdtest{% + \mediaquery{max-textwidth=4cm} + {\ResponsiveSetup{lineratio=38}\setsizes{45}} + {\ResponsiveSetup{lineratio=34}\setsizes{60}} + \lipsum[1] +} + +\begin{figure}[htbp] + % \centering + % \begin{subcaptionblock}{0.25\textwidth} + \caption{Change number of characters and line spacing depending on the text width using Media queries}\label{fig:mediaquery} + % \begin{subcaptiongroup} + \begin{subfigure}[t]{0.40\textwidth} + \centering + \begin{minipage}{4cm} + { \mdtest + + } + \end{minipage} + \caption{Text width of 4\,cm with 45 characters} + \end{subfigure} + \hfill + % \hspace{2em} + \begin{subfigure}[t]{0.55\textwidth} + \centering + \begin{minipage}{6cm} + { \mdtest + + } + \end{minipage} + \caption{Text width of 6\,cm with 60 characters} + \end{subfigure} + +\end{figure} + +The tests available in media queries are listed in Table~\ref{tbl:mediaqueries}. +Those expecting dimensional units also have variants using \texttt{min-} and \texttt{max-}, which +do not test exact values but rather whether the provided value is less than, +greater than, or equal to the tested parameter. Tests without these variants evaluate for an exact match. +The test for a two-column layout is special in that it does not expect any +testing values. It evaluates to true if the document uses the \texttt{twocolumn} option. + + + +\begin{table}[htbp] + \centering + \begin{tabular}{ll} + \toprule + test & possible values \\ + \midrule + textwidth & dimensional unit \\ + textheight & dimensional unit \\ + paperwidth & dimensional unit\\ + paperheight & dimensional unit\\ + orientation & landscape, portrait\\ + twocolumn & none \\ + \bottomrule + \end{tabular} + \caption{Tests available in media queries}\label{tbl:mediaqueries} +\end{table} + + + + +\section{Package Options} + +The following options can be passed as package options used in \cmd{\usepackage}, +or later in the document using the \cmd{\ResponsiveSetup} command. + +\medskip + +\noindent \DescribeKey{characters} Approximate number of characters that should fit to a text line. Default value is 66. + +\noindent \DescribeKey{noautomatic} Disable automatic setting of font sizes, line spacing and typographic scale in the document. You can set them +later using the \cmd{\setsizes} and \cmd{\ResponsiveSetup} commands. + +\noindent \DescribeKey{scale} Select named typographic scale. Default scale is +\texttt{tetratonic}, which is the most similar to the default scale used by +\LaTeX. + +\noindent \DescribeKey{number} The number of steps during which the text size is multiplied by the amount specified in the \texttt{ratio} option. + +\noindent \DescribeKey{ratio} The amount by which the font size will increase over a given number of steps. + +\noindent \DescribeKey{lineratio} The ratio used in calculating the line spacing. Default value is 33.3333, which should produce similar line spacing as the default \LaTeX\ setting. + +\noindent \DescribeKey{lineheight} Calculate line spacing by a fixed ratio, similarly to the CSS \texttt{lineheight} property. + +\noindent \DescribeKey{boxwidth} Width of line that is used for font size calculations in the \cmd{\setsizes} command. Default value is \cmd{\textwidth}. + + + + +\section{Commands} + +\StartDescribe\ResponsiveSetup +\cmd\ResponsiveSetup\marg{options} + +\noindent It allows you to reset the package options later in the document. You +need to call the \cmd{\setsizes} command to reset font sizes explicitly if you use this command +outside of the document preamble, or when using the \texttt{noautomatic} option. + +\StartDescribe\setsizes +\cmd\setsizes\oarg{line height ratio}\marg{number of characters per line} + +\noindent It sets the text size so that the specified average number of +characters fit on a line. If you do not provide the number of characters, the +package option \texttt{characters} will be used. + + +\StartDescribe\fonttobox +\cmd\fonttobox\oarg{line height ratio}\marg{text width}\marg{text} + +\noindent Set the text size so that the specified text in the second parameter has +the specified size in the first parameter. Optionally, you can set the line +height ratio. + +\StartDescribe\mediaquery +\cmd\mediaquery\marg{media query test}\marg{true code}\marg{false code} + +\noindent +It tests the document's properties using media queries and executes code based on the test results. +The code can typically use \cmd\ResponsiveSetup, but you can also execute any other commands. + +\StartDescribe\DeclareMediaQueryMatcher +\cmd\DeclareMediaQueryMatcher\marg{test name}\marg{\LaTeX\ 3 boolean query test} + +\noindent Declares a new test for a media query. The tests can use LaTeX 3 boolean tests, +and in case of a positive result, it must execute the command +\cmd\mediaquerytrue. + +\StartDescribe\fixtextheight +\cmd\fixtextheight + +\noindent It adjusts the page height, header, and footer to prevent underflow +\cmd{\vbox} warnings in the output routine. + + + +\section{Troubleshooting} + +Occasionally, you can run into issues caused by the change of font sizes. \LaTeX\ sets lot of parameters +depending on the base font size. We try to recalculate them according to the new font size, but you can still +experience some issues, described in following subsections. + +\subsection{Underfull \texttt{\textbackslash vbox} warning} + +Occasionally, you can get the following warning: + +\begin{verbatim} +Underfull \vbox (badness 6412) has occurred while \output is active [] +\end{verbatim} + +We calculate the page height that suits for the font size, but often, +we would get error when a bigger font is used on the page, +for example in chapters. When you set font sizes in the document preamble, +text height should be changed automatically. If you reset font sizes later in the +document, you need to use the \cmd{\fixtextheight} command. It should help in +most cases. If not, you can try the following hack. +This trick should fix \cmd{\vbox} errors in the output routine, but it can lead +to an irregular number of lines on pages. + + +\begin{verbatim} +\ExplSyntaxOn +\def\@textbottom{\vskip \z@ \@plus \resp_font_size \@minus \resp_font_size} +\ExplSyntaxOff +\end{verbatim} + +\section{License} + +Permission is granted to copy, distribute and/or modify this software +under the terms of the \LaTeX\ Project Public License, version 1.3. + + +\section{Changes} + +\begin{changelog} + \change{2023-12-13}{Version 0.1 released.} + \change{}{Finished documentation.} + \change{2023-12-07}{Added the \texttt{lineheight} property.} + \change{}{Use floating point numbers for the lineratio.} + \change{2023-12-06}{ChangeLog started.} +\end{changelog} +% \section{Examples} +% \PrintIndex + +\printbibliography[heading=bibintoc] + + + + + +\end{document} |