SF.net SVN: docutils:[9935 ] trunk/docutils/docs
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9935
http://sourceforge.net/p/docutils/code/9935
Author: milde
Date: 2024-09-20 08:32:28 +0000 (Fri, 20 Sep 2024)
Log Message:
-----------
Update documentation around length specifications.
Modified Paths:
--------------
trunk/docutils/docs/index.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docs/ref/rst/restructuredtext.rst
trunk/docutils/docs/user/latex.rst
trunk/docutils/docs/user/manpage.rst
Modified: trunk/docutils/docs/index.rst
===================================================================
--- trunk/docutils/docs/index.rst 2024-09-20 06:31:07 UTC (rev 9934)
+++ trunk/docutils/docs/index.rst 2024-09-20 08:32:28 UTC (rev 9935)
@@ -95,7 +95,7 @@
* `Docutils Mailing Lists <user/mailing-lists.html>`__
* `Docutils Link List <user/links.html>`__
-Writer-specific:
+_`Writer-specific`:
* `Docutils HTML Writers <user/html.html>`__
* `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__
* `Docutils LaTeX Writer <user/latex.html>`__
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2024-09-20 06:31:07 UTC (rev 9934)
+++ trunk/docutils/docs/ref/rst/directives.rst 2024-09-20 08:32:28 UTC (rev 9935)
@@ -194,7 +194,7 @@
.. _HTML4:
.. _html4 writer: ../../user/html.html#html4css1
.. _HTML5:
-.. _html5 writer: ../../user/html.html#html5-polyglot
+.. _html5 writer: ../../user/html.html#html5
.. _LaTeX: ../../user/latex.html#image-inclusion
.. _ODT: ../../user/odt.html
.. _manpage: ../../user/manpage.html
@@ -289,9 +289,9 @@
``scale`` : integer percentage (the "%" symbol is optional)
The uniform scaling factor of the image. The default is "100 %",
i.e. no scaling.
- Docutils tries to determine dimensions from the image file
- if no ``height`` or ``width`` options are specified
- (requires the `Python Imaging Library`_).
+ If the output format does not support a scaling attribute (e.g. HTML),
+ the Docutils writer tries to determine missing size specifications from
+ the image file (requires the `Python Imaging Library`_).
.. _target:
@@ -312,8 +312,8 @@
The behaviour may change for the ODT and XML writers but
images cannot be embedded in a LaTeX source.
-.. [#] SVG images are directly included, other images are base64_ encoded
- and included as a `data URI`_.
+.. [#] The `HTML5 writer`_, embeds SVG images directly and other images
+ as base64_ encoded `data URI`_.
.. _lazy loading attribute: https://html.spec.whatwg.org/multipage/
urls-and-fetching.html#lazy-loading-attributes
@@ -1107,9 +1107,9 @@
"auto" delegates the determination of column widths to the backend
(LaTeX, the HTML browser, ...).
- .. TODO
- Add option ``missing-cells`` with keywords "strict", "fill", "span"?
- (cf. [feature-requests:#103])
+.. TODO
+ Add option ``missing-cells`` with keywords "strict", "fill", "span"?
+ (cf. [feature-requests:#103])
----------------
@@ -2167,7 +2167,7 @@
.. image:: bild.png
:alt: example picture
- :name: my picture
+ :name: my picture
is the recommended syntax alternative to a preceding
`hyperlink target`_ ::
@@ -2204,7 +2204,7 @@
A _`list of integers` may be comma- or whitespace-separated.
:_`length`: number, optionally followed by one of the
- supported `length units`_
+ `supported length units`_
Handling of values without unit depends on the writer/output format.
See the writer specific documentation in the `user doc`__ for details.
@@ -2217,6 +2217,11 @@
The `root_prefix`_ configuration setting can be used to tell Docutils
to interpret paths starting with "/" relative to a "project directory".
+:_`percentage`: number followed by the percent sign '%'
+
+ Percentage values are relative to other values, depending on the
+ context in which they occur.
+
:_`text`: free text
Possible restrictions are given in parentheses.
@@ -2241,8 +2246,7 @@
restructuredtext.html#external-hyperlink-targets
.. _hyperlink references: restructuredtext.html#hyperlink-references
.. _hyperlink target: restructuredtext.html#hyperlink-targets
-.. _length units: restructuredtext.html#length-units
-.. _percentage: restructuredtext.html#percentage-units
+.. _supported length units: restructuredtext.html#length-units
.. _reference name:
.. _reference names: restructuredtext.html#reference-names
.. _reStructuredText table: restructuredtext.html#tables
Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst 2024-09-20 06:31:07 UTC (rev 9934)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst 2024-09-20 08:32:28 UTC (rev 9935)
@@ -3072,55 +3072,66 @@
RFC3986_.
-Units
-=====
+Measures and Units
+==================
-All measures consist of a positive floating point number in standard
-(non-scientific) notation and a unit, possibly separated by one or
-more spaces.
+*Measures* consist of a positive floating point number in standard
+(non-scientific) notation and an optional unit, possibly separated
+by one or more spaces.
-Units are only supported where explicitly mentioned in the reference
-manuals.
+Measures are only supported where explicitly mentioned in the reference
+manuals (`directive option`_ values of type "length__" or "percentage__").
+In the `document tree`_, they are stored in attributes of type `measure`_.
+.. _directive option: `directive options`_
+__ directives.html#length
+__ directives.html#percentage
+
Length Units
------------
-The following length units are supported by the reStructuredText
-parser:
+The reStructuredText parser supports the `length units in CSS2`_. [#]_
+Unit identifiers are case-sensitive (in contrast to CSS):
-* 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)
+.. class:: align-center
-This set corresponds to the `length units in CSS2`_ (a subset of `length
-units in CSS3`_).
+==== ======================= ================================
+em the element's font size
+---- ---------------------------------------------------------
+ex x-height of the element's font
+---- ---------------------------------------------------------
+cm centimeters 1 cm = 10 mm
+mm millimeters 1 mm = 1/1000 m
+in inches 1 in = 2.54 cm = 96 px
+pc picas 1 pc = 1/6 in = 12 pt
+pt points 1 pt = 1/72 in
+px pixels 1 px = 3/4 pt = 1/96 in [#]_
+==== ======================= ================================
-.. [#] 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", ".5 in", "42".
-The following are all valid length values: "1.5em", "20 mm", ".5in".
+It is up to the processing system to provide a fallback/workaround or
+raise an error if the output format does not support a unit or
+values without unit. For the behaviour of the Docutils writers,
+see the `writer documentation`_.
-Length values without unit are completed with a writer-dependent
-default (e.g. "px" with HTML, "pt" with `latex2e`). See the writer
-specific documentation in the `user doc`__ for details.
+.. [#] a subset of `length units in CSS3`_
+.. [#] In LaTeX, the default definition is 1 px = 1 pt = 1/72 in
+ (cf. section `Length units <../../user/latex.html#length-units>`__
+ in the LaTeX writer documentation).
.. _length units in CSS2:
https://www.w3.org/TR/CSS2/syndata.html#length-units
.. _length units in CSS3:
https://www.w3.org/TR/css-values-3/#lengths
-.. _How to configure the size of a pixel:
- ../../user/latex.html#size-of-a-pixel
-__ ../../index.html#introductory-tutorial-material-for-end-users
+.. _XSL units: https://www.w3.org/TR/xsl/#d0e5752
-Percentage Units
-----------------
+Percentage Unit
+---------------
+
Percentage values have a percent sign ("%") as unit. Percentage
values are relative to other values, depending on the context in which
they occur.
@@ -3143,6 +3154,8 @@
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Docutils: https://docutils.sourceforge.io/
+.. _writer documentation: ../../index.html#writer-specific
+
.. _character_level_inline_markup:
../../user/config.html#character-level-inline-markup
.. _footnote_references:
@@ -3249,6 +3262,7 @@
.. _`<version>`: ../doctree.html#version
.. _"classes" attribute: ../doctree.html#classes
.. _identifier key: ../doctree.html#identifiers
+.. _`measure`: ../doctree.html#measure
.. _metadata title: ../doctree.html#title-attribute
.. _Docutils Generic DTD: ../docutils.dtd
@@ -3257,6 +3271,7 @@
../../howto/i18n.html#docutils-language-module
.. _PEP 258: ../../peps/pep-0258.html
+.. _writer:
.. _writers: ../../peps/pep-0258.html#writers
.. _transforms: ../../api/transforms.html
Modified: trunk/docutils/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst 2024-09-20 06:31:07 UTC (rev 9934)
+++ trunk/docutils/docs/user/latex.rst 2024-09-20 08:32:28 UTC (rev 9935)
@@ -86,44 +86,54 @@
.. _docutils.sty: https://ctan.org/pkg/docutils
+.. _length unit:
Length units
------------
-LaTeX supports all `length units`_ defined for Docutils plus the
-following less common units:
+The LaTeX writer supports all `reStructuredText length units`_
+with the following peculiarities:
-.. class:: narrow
+* In LaTeX, the size of the *pixel unit* `can be configured
+ <size of a "px"_>`__. It defaults to **1 px = 1/72 in**
+ while the `CSS3 pixel unit`_ is defined as 1 px = 1/96 in.
-:dd: didôt (1 dd = 1238/1157 pt)
-:cc: cîcero (1 cc = 12 dd)
-:sp: scaled point (1sp = 1/65536pt)
-:bp: "big" point (`DTP point`) (1 bp = 1/72 in)
+* LaTeX uses "pt" for the `American point`_ (*TeX point*), 1 pt = 1/72.25 in.
+ The `DTP point`_ (*Postscript point*) used in CSS is available in LaTeX
+ as *big point*, 1 bp = 1/72 in.
-The **default length unit** (added by the latex writer to length
-values without unit) is the `DTP point` "bp".
+ Lengths specified in the source with unit "pt" are written with unit
+ "bp" by the LaTeX writer. In `raw LaTeX`_ and `custom style sheets`_,
+ the `DTP point` must be specified as "bp", while "pt" is interpreted as
+ `TeX point`.
-.. attention:: Different definitions of the unit "pt"!
+* The **default length unit** (added by the latex writer to length values
+ without unit) is the `DTP point` "**bp**". It will change to "px" in
+ Docutils 1.0.
- * In Docutils (as well as CSS) the unit symbol "pt" denotes the
- `Postscript point` (`DTP point`).
+The TeX units:
- * LaTeX uses "pt" for the typewriter's (or LaTeX) point,
- which is unknown to Docutils and 0.3 % smaller.
+.. class:: align-center
- * The `DTP point` is available in LaTeX as "bp" (big point):
+==== ========================= ===================
+ bp "big" point (`DTP point`) 1 bp = 1/72 in
+ cc cîcero 1 cc = 12 dd
+ dd didôt 1 dd = 1238/1157 pt
+ sp scaled point 1sp = 1/65536pt
+==== ========================= ===================
- 1 pt = 1/72.25 in < 1 bp = 1/72 in
+can be used in `raw LaTeX`_ and `custom style sheets`_ but not in
+reStructuredText.
- Lengths specified in the document with unit "pt" will be given the
- unit "bp" in the LaTeX source.
+.. _CSS3 pixel unit: https://www.w3.org/TR/css-values-3/#px
+.. _reStructuredText length units:
+ ../ref/rst/restructuredtext.html#length-units
+.. _American point:
+ https://en.wikipedia.org/wiki/Point_(typography)#American_points
+.. _DTP point:
+ https://en.wikipedia.org/wiki/Point_(typography)#Desktop_publishing_point
- In `raw LaTeX`_ and `custom style sheets`_, the `DTP point` must be
- specified as "bp", while "pt" is interpreted as `LaTeX point`.
-.. _length units: ../ref/rst/restructuredtext.html#length-units
-
-
PDF generation
==============
@@ -444,7 +454,7 @@
(Command ``\DUadmonition`` with legacy-class-functions_.)
Default:
- Typeset in a frame (90 % of text width).
+ Typeset in a frame (90 % of text width).
The admonition title is typeset with the ``\DUtitle`` command (see `titles`_).
@@ -609,10 +619,10 @@
``\DUdocinfowidth``: the width for the `docinfo` table.
Default:
- 90 % of text width: ``0.9\textwidth``
+ 90 % of text width: ``0.9\textwidth``
Example:
- set to 70 % of text width::
+ set to 70 % of text width::
\newlength{\DUdocinfowidth}
\setlength{\DUdocinfowidth}{0.7\textwidth}
@@ -687,7 +697,7 @@
caption numberings.
Some document classes (e.g. KOMA-script_) provide additional configuration.
-Also see the related `LaTeX FAQ entry`__
+See also `The style of captions`_ in the LaTeX FAQ.
Example
::
@@ -697,9 +707,8 @@
.. _caption: https://ctan.org/pkg/caption
.. _chngcntr: https://ctan.org/pkg/chngcntr
-__ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=running-nos
+.. _The style of captions: https://texfaq.org/FAQ-captsty
-
figure placement
----------------
@@ -1203,7 +1212,6 @@
__ ../ref/rst/restructuredtext.html#line-blocks
-
line spacing
------------
@@ -1605,31 +1613,24 @@
__ https://docutils.sourceforge.io/docutils/docs/ref/rst/directives.html#sidebar
-size of a pixel
----------------
+size of a "px"
+--------------
-The *physical size* of a pixel depends on the resolution of the output
-device and is usually specified in *dots per inch* (DPI).
+The `length unit`_ "px" is `defined in pdfTeX and LuaTeX`__, the "XeTeX"
+writer uses the ``\pdfpxdimen`` macro as workaround.
-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. [#]_
+ 1 px = 1/72 in
Example:
- Set the value to match the CSS definition
+ Set the value to match the `CSS3 pixel unit`_ 1 px = 1/96 in
with the `LaTeX code`_::
\pdfpxdimen=1in
- \divide\pdfpxdimen by 96 % 1/96 inch
+ \divide\pdfpxdimen by 96
-.. [#] The `CSS length unit ``px```_ defaults to 1/96 inch.
-
__ https://tex.stackexchange.com/questions/41370/
what-are-the-possible-dimensions-sizes-units-latex-understands
-.. _CSS length unit ``px``: https://www.w3.org/TR/css-values-3/#px
.. _reference pixel: https://www.w3.org/TR/css-values-3/#reference-pixel
table style
@@ -2004,23 +2005,15 @@
Why are my images too big?
``````````````````````````
-HTML-browsers use the actual screen resolution (usually around
-100 DPI).
+In LaTeX, the size of the *pixel unit* defaults to 1 px = 1/72 in
+while the `CSS3 pixel unit`_ is defined as 1 px = 1/96 in.
-The CSS specification suggests:
-
- It is recommended that the reference pixel be the visual angle of one
- pixel on a device with a pixel density of 96 DPI and a distance from the
- reader of an arm's length.
-
- -- https://www.w3.org/TR/CSS2/syndata.html#length-units
-
This is why pixmap images without size specification or objects with a size
-specified in ``px`` tend to come too large in the PDF.
+specified in ``px`` tend to come out too large in the PDF.
Solution:
- Specify the image size in fixed units (``pt``, ``cm``, ``in``) or
- configure the `size of a pixel`_ (length unit px).
+ Specify the image size in fixed `length units`_ (``pt``, ``cm``, ``in``, …)
+ or configure the `size of a "px"`_.
Error ``illegal unit px``
@@ -2033,11 +2026,7 @@
`pdfTeX` is used also for conversion into DVI format in all modern LaTeX
distributions (since ca. 2006).
-If updating LaTeX is not an option, just remove the "px" from the length
-specification. HTML/CSS will default to "px" while the `latexe2` writer
-will add the fallback unit "bp".
-
Error ``Symbol \textcurrency not provided`` ...
```````````````````````````````````````````````
@@ -2048,15 +2037,13 @@
(textcomp) font family ptm in TS1 encoding.
(textcomp) Default family used instead.
-(which in case of font family "ptm" is a false positive). Add either
+(which in case of font family "ptm" is a false positive).
-:warn: turn the error in a warning, use the default symbol (bitmap), or
-:force,almostfull: use the symbol provided by the font at the users
- risk,
+Add either ``warn`` (turn the error in a warning, use the default (bitmap)
+symbol), or ``force,almostfull`` (use the symbol provided by the font at
+the users risk) to the document options or use a different font package.
-to the document options or use a different font package.
-
Warning: language … not supported
`````````````````````````````````
Modified: trunk/docutils/docs/user/manpage.rst
===================================================================
--- trunk/docutils/docs/user/manpage.rst 2024-09-20 06:31:07 UTC (rev 9934)
+++ trunk/docutils/docs/user/manpage.rst 2024-09-20 08:32:28 UTC (rev 9935)
@@ -146,14 +146,27 @@
offers opening the standard browser to that URI ... assuming OSC8 is
supported.
-References
-==========
-Consult man pages from section 7: *man*, *man-pages*, *groff_man* and
-*groff_man_style*.
+Limitations
+===========
-.. [LMHT] `Linux Man Page Howto <https://tldp.org/HOWTO/Man-Page/>`__.
+The "manpage" writer does not support all `Docutils Document Tree`_ elements
+but a subset that is relevant for manual pages.
+The output is pure text, images are not included. Instead, the text
+description in their `"alt" attribute`_ is shown.
+
+.. TODO: a warning is given for image elements without `"alt" attribute`_.
+
+The "manpage" writer ignores element attributes specifying a measure_.
+
+.. _measure: ../ref/doctree.html#measure
+.. _"alt" attribute: ../ref/doctree.html#alt
+
+.. groff supports the CSS2 units except "ex", "mm", and "px"
+ https://www.gnu.org/software/groff/manual/groff.html#Measurements
+
+
Conventions
===========
@@ -176,8 +189,9 @@
but this is not done on typesetting devices like printers. Check your
output with a PostScript or PDF viewer before printing it.
-* [LMHT]_ Filenames are always in italics, except in C language
- preprocessor inclusions in the SYNOPSIS section. Use::
+* Filenames are always in italics, except in C language
+ preprocessor inclusions in the SYNOPSIS section. [LMHT]_
+ Use::
.I /usr/include/stdio.h
@@ -185,4 +199,14 @@
.B #include <stdio.h>
+
+References
+==========
+
+Consult man pages from section 7: *man*, *man-pages*, *groff_man* and
+*groff_man_style*.
+
+.. [LMHT] `Linux Man Page Howto <https://tldp.org/HOWTO/Man-Page/>`__.
+
.. _Docutils: https://docutils.sourceforge.io/
+.. _Docutils Document Tree: ../ref/doctree.html
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins