Commit 7677d787 authored by Etienne Nadji's avatar Etienne Nadji
Browse files

nouveau fichier : source/LICENSE

	nouveau fichier : source/_static/custom.css
	nouveau fichier : source/_static/logo-300.png
	nouveau fichier : source/articles/en/spec-suggestions.rst
	nouveau fichier : source/articles/en/spec.rst
	nouveau fichier : source/articles/fr/stories.rst
	nouveau fichier : source/conf.py
	nouveau fichier : source/credits.rst
	nouveau fichier : source/examples/index.rst
	nouveau fichier : source/examples/wireframe.rst
	nouveau fichier : source/guide/en/psm.rst
	nouveau fichier : source/guide/en/quickstart.rst
	nouveau fichier : source/guide/en/templating.rst
	nouveau fichier : source/guide/fr/dims.rst
	nouveau fichier : source/guide/fr/general.rst
	nouveau fichier : source/index.rst
	nouveau fichier : source/modules.rst
	nouveau fichier : source/pyscribus.rst
	nouveau fichier : source/pyscribus/__init__.py
	nouveau fichier : source/pyscribus/colors.py
	nouveau fichier : source/pyscribus/common/__init__.py
	nouveau fichier : source/pyscribus/common/math.py
	nouveau fichier : source/pyscribus/common/xml.py
	nouveau fichier : source/pyscribus/dimensions.py
	nouveau fichier : source/pyscribus/document.py
	nouveau fichier : source/pyscribus/exceptions.py
	nouveau fichier : source/pyscribus/extra/__init__.py
	nouveau fichier : source/pyscribus/extra/wireframe.py
	nouveau fichier : source/pyscribus/itemattribute.py
	nouveau fichier : source/pyscribus/logs.py
	nouveau fichier : source/pyscribus/marks.py
	nouveau fichier : source/pyscribus/notes.py
	nouveau fichier : source/pyscribus/pageobjects.py
	nouveau fichier : source/pyscribus/pages.py
	nouveau fichier : source/pyscribus/papers/__init__.py
	nouveau fichier : source/pyscribus/papers/afnor.py
	nouveau fichier : source/pyscribus/papers/ansi.py
	nouveau fichier : source/pyscribus/papers/iso216.py
	nouveau fichier : source/pyscribus/papers/iso217.py
	nouveau fichier : source/pyscribus/papers/iso269.py
	nouveau fichier : source/pyscribus/papers/newspaper.py
	nouveau fichier : source/pyscribus/patterns.py
	nouveau fichier : source/pyscribus/printing.py
	nouveau fichier : source/pyscribus/sla.py
	nouveau fichier : source/pyscribus/stories.py
	nouveau fichier : source/pyscribus/styles.py
	nouveau fichier : source/pyscribus/toc.py
	nouveau fichier : source/setup.py
	nouveau fichier : source/test-colors.py
	nouveau fichier : source/test-dims.py
	nouveau fichier : source/test-html-stories.py
	nouveau fichier : source/test-load-export.py
	nouveau fichier : source/test-metopes.py
	nouveau fichier : source/test-new.py
	nouveau fichier : source/test-onix.py
	nouveau fichier : source/test-styles-import.py
	nouveau fichier : source/test-templating.py
	nouveau fichier : source/test-wireframe.py
	nouveau fichier : source/thanks.rst
parent c2a2c0b6
This diff is collapsed.
/* vim: set wrap breakindent: */
html {
background-color: #1f2532;
}
body {
font-family: Ubuntu, Cantarell, sans-serif;
}
@media only screen and (min-width: 768px) {
.wy-body-for-nav {
max-width: 1100px;
margin: 0 auto;
}
}
@media only screen and (min-width: 768px) {
.wy-nav-side {
left: inherit;
}
}
.wy-menu-vertical a:hover {
background-color: #252c3c;
}
.wy-side-nav-search {
background-color: white;
}
.wy-side-nav-search > div.version {
color: black;
}
.wy-side-nav-search a {
color: black;
}
.wy-nav-side {
background-color: #2172a5;
}
*****************************
SLA's enhancement suggestions
*****************************
# 1
===
The case used of element names and attributes should be clearly defined and homogeneous.
Discussion
----------
Almost every text case is used for element's names attributes. But XML/XSL tools
are case sensitive by default.
Why ``DOCUMENT/MASTERPAGE``, ``DOCUMENT/PAGEOBJECT/LATEX/PROPERTY``,
``DOCUMENT/Sections/Section`` ?
# 2
===
Render frames buffers should use a generic element name instead of `LATEX`,
as they link to a configuration file and they no more render only LaTeX code.
Discussion
----------
It makes no sense to have a LATEX element with GnuPlot instructions.
# 3
===
Attribute names should be in only one language, so the remaining german
attributes should be translated.
Discussion
----------
``<LAYERS NUMMER="0" LEVEL="0" NAME="Fond de page" SICHTBAR="1" DRUCKEN="1" EDIT="1" SELECT="0" FLOW="1" TRANS="1" BLEND="0" OUTL="0" LAYERC="#000000"/>``
[EN] SLA document-able attributes
=================================
In all XPath location path listed here, we omit ``/SCRIBUSUTF8NEW/DOCUMENT``.
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| XML | Explanation | Value | Default | Optional |
| element/attribute | | | | |
+===================================+=======================+====================+==================+==========+
| ``/@DPInCMYK`` | ICC profile for CMYK | string | | Yes |
| | images | | | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/@DPIn3`` | ICC profile for CMYK | string | | Yes |
| | colors | | | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/@PAGEC`` | Scribus GUI page | hexadecimal color | ``#ffffff`` | |
| | background | | | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/LAYERS/@FLOW`` | | integer as boolean | | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/LAYERS/@TRANS`` | Layer’s opacity | percentage | ``1`` | |
| | | 0 -> 1 | | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/LAYERS/@BLEND`` | Layer blend mode | | | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/LAYERS/@OUTL`` | Flag for wireframe | integer as boolean | ``0`` | |
| | view | | | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/LAYERS/@LAYERS`` | Color outline of the | hexadecimal color | | |
| | layer’s frames | | | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/CHARSTYLE/@DefaultStyle`` | Same as STYLE, but | string | | |
| | not documented | | | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/Sections/Section/@FillChar`` | | Unicode code | ``0`` | |
| | | point of character | (NULL character) | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
| ``/Sections/Section/@FieldWidth`` | | | ``0`` | |
+-----------------------------------+-----------------------+--------------------+------------------+----------+
Corrections
-----------
For ``Sections/Section/@Type``, the possible values are incomplete in the wiki.
The complete possible values are :
- Type_1_2_3
- Type_1_2_3_ar
- Type_i_ii_iii
- Type_I_II_III
- Type_a_b_c
- Type_A_B_C
- Type_Alphabet_ar
- Type_Abjad_ar
- Type_Hebrew
- Type_asterix
- Type_CJK
Notable things
--------------
``/Marks/Mark[@type="3"]`` (variable text mark) ``@str`` attribute is used like
the ``@label`` attribute of ``/Marks/Mark[@type!="3"]``.
[FR] Comment les *stories* de Scribus (semblent) fonctionner
============================================================
Les *stories* de Scribus sont contenues dans des éléments XML
``StoryText`` et comportent en séquence les élements XML suivants :
================ ========================
Élement XML Usage
================ ========================
``DefaultStyle`` Remise à zéro des styles
``ITEXT`` Fragment de texte
``para`` Fin de paragraphe
``MARK`` Marque de référence
``breakline`` Retour à la ligne forcé
``trail`` Fin de *story*
================ ========================
``DefaultStyle`` remet les styles à zéro et est systématiquement le
premier enfant de ``StoryText`` (sans doute pour éviter une
contamination des styles à la suite d’une erreur).
Comment faire un paragraphe
---------------------------
Les *stories* de Scribus n’emploient pas d’éléments XML imbriqués, pas
plus qu’ils n’emploient d’éléments XML ayant un contenu (tout se passe
dans les attributs, c’est une tendance générale du SLA).
On ne peut donc pas repérer un paragraphe parce qu’il constitue un
élement XML unique.
.. note:: En fait si, mais seulement si le paragraphe est vide.
Un paragraphe d’une *story* Scribus est une séquence de fragments de
texte ayant des caractéristiques de mises en forme différentes, de
marqueurs de retour à la ligne manuels, de marques de références, se
terminant par un marqueur de fin de paragraphe.
Ainsi le paragraphe suivant :
| Scribus est un *logiciel*
| libre.
donnera dans une *story* :
.. code:: xml
<ITEXT CH="Scribus est un " />
<ITEXT FONT="Arial Italic" CH="logiciel" />
<breakline />
<ITEXT CH="libre" />
<para/>
Et un paragraphe vide donnera :
.. code:: xml
<para/>
<para/>
…où le premier ``para`` est la fin du paragraphe précédent (vide ou
non).
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
import pyscribus
# -- Project information -----------------------------------------------------
project = 'PyScribus'
copyright = "2020, Étienne Nadji"
author = 'Étienne Nadji'
# The short X.Y version
version = pyscribus.__version__
# The full version, including alpha/beta/rc tags
release = pyscribus.__version__
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- Options for HTML output -------------------------------------------------
# html_theme = 'alabaster'
# html_theme_options = {
# "show_powered_by": False,
# "show_related": False,
# }
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_static_path = ['_static']
html_logo = '_static/logo-300.png'
html_css_files = ['custom.css',]
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
html_sidebars = {
"*": ["sidebarintro.html", "searchbox.html", "localtoc.html"],
"articles/*/*": ["sidebarintro.html", "searchbox.html", "localtoc.html"],
"guide/*/*": ["sidebarintro.html", "searchbox.html", "localtoc.html"],
}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'PyScribusDoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
'papersize': 'a4paper',
'pointsize': '12pt',
# Additional stuff for the LaTeX preamble.
'preamble': '',
# Latex figure (float) alignment
'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'PyScribus.tex', 'PyScribus Documentation',
'Étienne Nadji', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'pyscribus', 'PyScribus Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'PyScribus', 'PyScribus Documentation',
author, 'PyScribus', 'Python library for SLA (Scribus) files.',
'Miscellaneous'),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
# epub_identifier = ''
# A unique identification for the text.
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# -- Extension configuration -------------------------------------------------
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
*******
Credits
*******
Logo
====
.. image:: _static/logo.png
:align: center
:scale: 15%
PyScribus logo is a modified version of `the official Scribus icon <https://wiki.scribus.net/canvas/Promotion_material>`_, licenced under `CC-BY-SA 3.0 <https://creativecommons.org/licenses/by-sa/3.0>`_.
Examples
========
.. toctree::
:maxdepth: 1
wireframe.rst
Draw a wireframe of a file
--------------------------
::
import pyscribus.sla as sla
import pyscribus.extra.wireframe as wire
slafile = sla.SLA("wireframe_example.sla", "1.5.5")
wireframe = wire.Wireframe()
wireframe.from_sla(slafile)
wireframe.draw(
output="wireframe_example.png",
stylesheet=True,
margins=[10, 10]
)
.. figure:: ../_static/logo.png
:align: center
:scale: 15%
Original SLA file
.. figure:: ../_static/logo.png
:align: center
:scale: 15%
Wireframe
**********************
PyScribus Story Markup
**********************
PyScribus Story Markup is a mix between HTML and new elements of markup.
It is possible to use only HTML markup through ``<span>`` ``@style`` and ``@class`` attributes.
Main elements
*************
+---------------+---------------------------------+----------------+
| Tag(s) | Usage | HTML status |
+===============+=================================+================+
| ``em``, ``i`` | | OK |
+---------------+---------------------------------+----------------+
| ``b``, | Bold | OK |
| ``strong`` | | |
+---------------+---------------------------------+----------------+
| ``sup`` | Superscript | OK |
+---------------+---------------------------------+----------------+
| ``sub`` | Subscript | OK |
+---------------+---------------------------------+----------------+
| ``br`` | Line break | OK |
+---------------+---------------------------------+----------------+
| ``span`` | Various. See Span table | OK |
+---------------+---------------------------------+----------------+
| ``u`` | Underlined text (span alias) | Deprecated for |
| | | underlining |
| | | usage |
+---------------+---------------------------------+----------------+
| ``sc`` | Text in small caps (span alias) | Not in HTML |
+---------------+---------------------------------+----------------+
| ``pgno`` | Scribus variable: page number | Not in HTML |
+---------------+---------------------------------+----------------+
| ``pgco`` | Scribus variable: page count | Not in HTML |
+---------------+---------------------------------+----------------+
| ``note`` | (End/Foot)note. Note ID in | Not in HTML |
| | ``@id``. | |
+---------------+---------------------------------+----------------+
Span element
************
@style
======
+---------------------+-----------------------+-----------------------+
| @style property | Property value | Usage |
+=====================+=======================+=======================+
| ``font-variant`` | small-caps | Small caps |
+---------------------+-----------------------+-----------------------+
| ``text-transform`` | uppercase | Uppercase / All caps |
+---------------------+-----------------------+-----------------------+
| ``text-decoration`` | underline | Underlined text |
+---------------------+-----------------------+-----------------------+
| ``class`` | See Span @class table | See Span @class table |
+---------------------+-----------------------+-----------------------+
@class
======
+-----------------+-------------------------------+
| @class property | Usage |
+=================+===============================+
| ``pgno`` | Scribus variable: page number |
+-----------------+-------------------------------+
| ``pgco`` | Scribus variable: page count |
+-----------------+-------------------------------+
| ``note`` | (End/Foot)note. Note ID in |
| | span ``@id``. |
+-----------------+-------------------------------+
**********
Quickstart
**********
An introduction to PyScribus modules
====================================
Used for parsing & generating
-----------------------------
+-------------+-------------------------------+
| Module | Use |
+=============+===============================+
| sla | SLA file |
+-------------+-------------------------------+
| document | SLA document |
+-------------+-------------------------------+
| dimensions | Measures used in SLA |
+-------------+-------------------------------+
| colors | Colors and gradients |
+-------------+-------------------------------+
| patterns | Patterns |
+-------------+-------------------------------+
| pages | Pages |
+-------------+-------------------------------+
| pageobjects | Page objects |
+-------------+-------------------------------+
| marks | Marks |
+-------------+-------------------------------+
| stories | Stories |
+-------------+-------------------------------+
| notes | Notes |
+-------------+-------------------------------+
| styles | SLA styles |
+-------------+-------------------------------+
| toc | Sections & Tables of contents |
+-------------+-------------------------------+
| printing | Printing settings |
+-------------+-------------------------------+
Paper sizes
-----------
Theses modules define the width and height of many paper formats in the unit
Scribus handle (See **Measures and geometry in PyScribus**).
You will just need ``papers.iso216`` if you don't work in an
american / canadian context.
+---------------+---------------------------+
| Module | Use |
+===============+===========================+
| papers.iso216 | ISO 216 sizes (A, B) |
| | |
| | Examples : A4; A3 |
+---------------+---------------------------+
| papers.iso269 | ISO 269 sizes (C, DL) |
| | |
| | Examples : C6; DL |
+---------------+---------------------------+
| papers.iso217 | ISO 217 sizes (RA, SRA) |
| | |
| | Examples : RA0; 2SRA0 |
+---------------+---------------------------+
| papers.ansi | ANSI normalized sizes. |
| | |
| | Example : Letter / ANSI A |
+---------------+---------------------------+
| papers.afnor | AFNOR normalized sizes |
| | |
| | Examples : Raisin; Jesus |
+---------------+---------------------------+
Extras
------
Theses modules are shipped with PyScribus but may requires other python
libraries.
+-------------+-----------------------+----------------------------------------+
| Module | Use | Additionnal requirements |
+=============+=======================+========================================+
| wireframe | Drawing SLA wireframe | `Pillow <https://python-pillow.org/>`_ |
+-------------+-----------------------+----------------------------------------+
Basis
-----
Theses "low-level" (XML utilities and abstract classes) modules are used by
most of the other ones.
+-------------+-------------------------------+
| Module | Use |
+=============+===============================+
| common.xml | Common XML parsing utilities |
+-------------+-------------------------------+
| common.math | Common math values |
+-------------+-------------------------------+
| exceptions | PyScribus exceptions |
+-------------+-------------------------------+
Basics of PyScribus objects
===========================
TODO: fromdefault(), pyscribus_defaults attribute, listdefaults()
Measures and geometry in PyScribus
==================================
As Scribus is used among users of metric and imperial systems, it must manage
length notation through a common unit in the SLA format (not in Scribus GUI),