From 636da5df1aead935bf093cf82d5dac361cc7a795 Mon Sep 17 00:00:00 2001 From: milde Date: Mon, 27 Nov 2017 11:07:28 +0000 Subject: [PATCH] Update documentation of length units. The "px" length unit is defined as an absolute length (with different conversion values) by CSS and (pdf)LaTeX. Thanks to Laurin McLaurin for pointing this out. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@8205 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/ref/rst/restructuredtext.txt | 33 +++++++++++++++++------------- docutils/docs/user/latex.txt | 26 +++++++++++++++-------- 2 files changed, 36 insertions(+), 23 deletions(-) diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt index 9421d8bd8..6123dc286 100644 --- a/docutils/docs/ref/rst/restructuredtext.txt +++ b/docutils/docs/ref/rst/restructuredtext.txt @@ -3026,31 +3026,36 @@ Length Units The following length units are supported by the reStructuredText parser: -* em (ems, the height of the element's font) -* ex (x-height, the height of the letter "x") -* px (pixels, relative to the canvas resolution) -* in (inches; 1in=2.54cm) -* cm (centimeters; 1cm=10mm) -* mm (millimeters) -* pt (points; 1pt=1/72in) -* pc (picas; 1pc=12pt) +* em (em unit, the element's font size) +* ex (ex unit, x-height of the element’s font) +* mm (millimeters; 1 mm = 1/1000 m) +* cm (centimeters; 1 cm = 10 mm) +* in (inches; 1 in = 2.54 cm = 96 px) +* px (pixels, 1 px = 1/96 in) [#]_ +* pt (points; 1 pt = 1/72 in) +* pc (picas; 1 pc = 1/6 in = 12 pt) -This set corresponds to the `length units in CSS`_. +This set corresponds to the `length units in CSS2`_ (a subset of `length +units in CSS3`_). -(List and explanations taken from -http://www.htmlhelp.com/reference/css/units.html#length.) +.. [#] In LaTeX, the default definition is 1 px = 1/72 in (cf. `How to + configure the size of a pixel`_ in the LaTeX writer documentation). The following are all valid length values: "1.5em", "20 mm", ".5in". Length values without unit are completed with a writer-dependent -default (e.g. px with `html4css1`, pt with `latex2e`). See the writer +default (e.g. "px" with HTML, "pt" with `latex2e`). See the writer specific documentation in the `user doc`__ for details. -.. _length units in CSS: +.. _length units in CSS2: http://www.w3.org/TR/CSS2/syndata.html#length-units - +.. _length units in CSS3: + http://www.w3.org/TR/css-values-3/#absolute-lengths +.. _How to configure the size of a pixel: + ../../user/latex.html#size-of-a-pixel __ ../../user/ + Percentage Units ---------------- diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt index 22943e854..38084e55c 100644 --- a/docutils/docs/user/latex.txt +++ b/docutils/docs/user/latex.txt @@ -1602,21 +1602,29 @@ __ http://docutils.sf.net/docutils/docs/ref/rst/directives.html#sidebar size of a pixel --------------- -The length unit ``px`` is a "relative length" whose value depends on the -*resolution* of the output device (usually specified in *dots per inch* -(DPI). However, when producing a PDF, the resolution of the output device -(printer, screen (for PDF-viewer)) is generally not known. +The *physical size* of a pixel depends on the resolution of the output +device and is usually specified in *dots per inch* (DPI). -With pdftex, the "resolution" is a configuration setting. +The *length unit* "px" is defined by the output format. For LaTeX, it is +`defined in pdfTeX and LuaTeX`__ (the `xetex` writer emulates this +definition). Default: - 72 DPI, i.e. 1 px = 1/72 in. + 72 DPI, i.e. 1 px = 1/72 in. [#]_ Example: - Set a resolution of 96 DPI with the `LaTeX code`_:: + Set the value to match the CSS definition + with the `LaTeX code`_:: - \pdfpxdimen=1in % 1 DPI - \divide\pdfpxdimen by 96 % 96 DPI + \pdfpxdimen=1in + \divide\pdfpxdimen by 96 % 1/96 inch + +.. [#] The `CSS length unit ``px```_ defaults to 1/96 inch. + +__ http://tex.stackexchange.com/questions/41370/ + what-are-the-possible-dimensions-sizes-units-latex-understands +.. _CSS length unit ``px``: http://www.w3.org/TR/css-values-3/#px +.. _reference pixel: http://www.w3.org/TR/css-values-3/#reference-pixel table ----- -- 2.11.4.GIT