diff --git a/docs/page.rst b/docs/page.rst index e6d67f82e..32f729a08 100644 --- a/docs/page.rst +++ b/docs/page.rst @@ -643,16 +643,16 @@ In a nutshell, this is what you can do with PyMuPDF: PDF only. Insert text into the specified rectangle. The method has similarities with methods :meth:`Page.insert_textbox` and :meth:`TextWriter.fill_textbox`, but is **much more powerful**. This is achieved by letting a :ref:`Story` object do all the required processing. - * Parameter "text" may be a string as in the other methods. But it will be **interpreted as HTML source** and may therefore also contain HTML language elements -- including styling. The "css" parameter may be used to pass in additional styling instructions. + * Parameter `text` may be a string as in the other methods. But it will be **interpreted as HTML source** and may therefore also contain HTML language elements -- including styling. The `css` parameter may be used to pass in additional styling instructions. * Automatic line breaks are inserted at word boundaries. The "soft hyphen" character `"­"` can be used to cause hyphenation and thus also cause line breaks. **Forced** line breaks however are only achievable via the HTML tag `
` - `"\\n"` is ignored and will be treated like a space. * With this method the following can be achieved: - Styling effects like bold, italic, text color, text alignment, font size or font switching. - - The text may inlude arbitrary languages -- **including rigt-to-left** languages. + - The text may inlude arbitrary languages -- **including right-to-left** languages. - Scripts like `Devanagari `_ and several others in Asia have a highly complex system of ligatures, where two or more unicodes together yield one glyph. The Story uses the software package `HarfBuzz `_ , to deal with these things and produce correct output. - - One can also **include images** via HTML tag `` -- the Story code will take care of the appropriate layout. This is an alternative option to insert images, compared to :meth:`Page.insert_image`. + - One can also **include images** via HTML tag `` -- the Story will take care of the appropriate layout. This is an alternative option to insert images, compared to :meth:`Page.insert_image`. - HTML tables (tag ``) may be included in the text and will be handled appropriately. - Links are automatically generated when present. @@ -663,9 +663,9 @@ In a nutshell, this is what you can do with PyMuPDF: :arg rect_like rect: rectangle on page to receive the text. :arg str,Story text: the text to be written. Can contain plain text and HTML tags with styling instructions. Alternatively, a :ref:`Story` object may be specified (in which case the internal Story generation step will be omitted). A Story must have been generated with all required styling and Archive information. - :arg str css: optional string containing additional CSS instructions. Ignored if "text" is a Story. + :arg str css: optional string containing additional CSS instructions. Ignored if `text` is a Story. :arg float scale_low: if necessary scale down the content until it fits in the target rectangle. This sets the down scaling limit. Detault is 0, no limit. A value of 1 means no down-scaling. A value of e.g. 0.2 means maximum down-scaling by 80%. - :arg Archive archive: an Archive object that points to locations where to find images or non-standard fonts. If "text" refers to images, this parameter is always reqired. Ignored if "text" is a Story. + :arg Archive archive: an Archive object that points to locations where to find images or non-standard fonts. If `text` refers to images, this parameter is always reqired. Ignored if `text` is a Story. :arg int rotate: one of the values 0, 90, 180, 270. Depending on this, text will be filled: - 0: top-left to bottom-right. @@ -674,15 +674,14 @@ In a nutshell, this is what you can do with PyMuPDF: - 270: top-right to bottom-left. .. image:: images/img-rotate.* - :scale: 50 :arg int oc: the xref of an :data:`OCG` / :data:`OCMD` or 0. Please refer to :meth:`Page.show_pdf_page` for details. :arg bool overlay: put the text in front of other content. Please refer to :meth:`Page.show_pdf_page` for details. :returns: A tuple of floats (spare_height, scale). - - **spare_height**: -1 if content did not fit, else >= 0. It is the height of the unused (still available) rectangle stripe. Positive only if scale = 1 (no down-scaling happened). - - **scale**: down-scaling factor, 0 < scale <= 1. + - `spare_height`: -1 if content did not fit, else >= 0. It is the height of the unused (still available) rectangle stripe. Positive only if scale = 1 (no down-scaling happened). + - `scale`: down-scaling factor, 0 < scale <= 1. Please refer to examples in this section of the recipes: :ref:`RecipesText_I_c`. diff --git a/docs/recipes-text.rst b/docs/recipes-text.rst index f9b923b64..a41000ae6 100644 --- a/docs/recipes-text.rst +++ b/docs/recipes-text.rst @@ -463,9 +463,8 @@ Please note how the "css" parameter is used to globally select the default "sans The result will look like this: .. image:: images/img-htmlbox1.* - :scale: 30 -Here is another example that outputs a table with this method. This time, we are including all the styling in the HTML source itself. Please also not, how it works to also include an image - even within a table cell:: +Here is another example that outputs a table with this method. This time, we are including all the styling in the HTML source itself. Please also note, how it works to include an image - even within a table cell:: import fitz_new as fitz import os @@ -529,7 +528,6 @@ Here is another example that outputs a table with this method. This time, we are The result will look like this: .. image:: images/img-htmlbox2.* - :scale: 30 Our third example will demonstrate the automatic multi-language support that also includes text shaping for complex scripting systems like Devanagari and right-to-left languages:: @@ -563,6 +561,5 @@ Our third example will demonstrate the automatic multi-language support that als And this is the output: .. image:: images/img-htmlbox3.* - :scale: 50 .. include:: footer.rst