← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/python-docutils/jaunty

« back to all changes in this revision

Viewing changes to docs/user/config.txt

  • Committer: Bazaar Package Importer
  • Author(s): Simon McVittie
  • Date: 2008-07-24 10:39:53 UTC
  • mfrom: (1.1.4 upstream) (3.1.7 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080724103953-8gh4uezg17g9ysgy
Tags: 0.5-2
http://bugs.debian.org/474941
* Upload docutils 0.5 to unstable
* Update rst.el to upstream Subversion r5596, which apparently fixes
  all its performance problems (17_speed_up_rst_el.dpatch, closes: #474941)

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/user/config.txt
1
 
==============================
2
 
 Docutils Configuration Files
3
 
==============================
 
1
========================
 
2
 Docutils Configuration
 
3
========================
4
4
 
5
5
:Author: David Goodger
6
6
:Contact: goodger@python.org
7
 
:Revision: $Revision: 4207 $
8
 
:Date: $Date: 2005-12-14 03:10:34 +0100 (Wed, 14 Dec 2005) $
 
7
:Revision: $Revision: 5505 $
 
8
:Date: $Date: 2008-01-26 02:50:57 +0100 (Sam, 26 Jän 2008) $
9
9
:Copyright: This document has been placed in the public domain.
10
10
 
 
11
.. sidebar:: Docutils Security for Web Applications
 
12
 
 
13
   For details about securing web applications, please see `Deploying
 
14
   Docutils Securely <../howto/security.html>`_.
 
15
 
11
16
.. contents::
12
17
 
13
 
.. Cross-reference command-line options with configuration file
14
 
   settings?  Make alphabetical indexes of both.
 
18
 
 
19
-------------------
 
20
Configuration Files
 
21
-------------------
15
22
 
16
23
Configuration files are used for persistent customization; they can be
17
24
set once and take effect every time you use a front-end tool.
61
68
Configuration File Syntax
62
69
-------------------------
63
70
 
64
 
Configuration files use the standard ConfigParser.py_ Python_ module.
65
 
From its documentation:
 
71
Configuration files are UTF-8-encoded text files.  The
 
72
ConfigParser.py_ module from Python_'s standard library is used to
 
73
read them.  From its documentation:
66
74
 
67
75
    The configuration file consists of sections, lead by a "[section]"
68
76
    header and followed by "name: value" entries, with continuations
85
93
* Off: "false", "no", "off", "0", "" (no value)
86
94
 
87
95
 
 
96
Example
 
97
=======
 
98
 
 
99
This is the contents of the ``tools/docutils.conf`` configuration file
 
100
supplied with Docutils::
 
101
 
 
102
    # These entries affect all processing:
 
103
    [general]
 
104
    source-link: yes
 
105
    datestamp: %Y-%m-%d %H:%M UTC
 
106
    generator: on
 
107
 
 
108
    # These entries affect HTML output:
 
109
    [html4css1 writer]
 
110
    # Required for docutils-update, the website build system:
 
111
    stylesheet-path: ../docutils/writers/html4css1/html4css1.css
 
112
    embed-stylesheet: no
 
113
    field-name-limit: 20
 
114
 
 
115
Individual configuration sections and settings are described in the
 
116
following section.
 
117
 
 
118
 
88
119
-------------------------------------
89
120
Configuration File Sections & Entries
90
121
-------------------------------------
149
180
 
150
181
    Default: "id".  Options: ``--auto-id-prefix`` (hidden, intended
151
182
    mainly for programmatic use).
152
 
    
 
183
 
153
184
_`datestamp`
154
185
    Include a time/datestamp in the document footer.  Contains a
155
186
    format string for Python's ``time.strftime``.  See the `time
262
293
 
263
294
    Default: "" (empty).  Options: ``--id-prefix`` (hidden, intended
264
295
    mainly for programmatic use).
265
 
    
 
296
 
266
297
_`input_encoding`
267
298
    The text encoding for input.
268
299
 
369
400
    Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
370
401
    for development use only).
371
402
 
 
403
_`strip_classes`
 
404
    List of "classes" attribute values to remove from all elements in
 
405
    the document tree.
 
406
 
 
407
    .. WARNING:: Potentially dangerous; use with caution.
 
408
 
 
409
    Default: disabled (None).  Option: ``--strip-class``.
 
410
 
372
411
_`strip_comments`
373
412
    Enable the removal of comment elements from the document tree.
374
413
 
375
 
    Default: disabled (None).  Options: ``--strip-comment``,
 
414
    Default: disabled (None).  Options: ``--strip-comments``,
376
415
    ``--leave-comments``.
377
416
 
 
417
_`strip_elements_with_classes`
 
418
    List of "classes" attribute values; matching elements to be
 
419
    removed from the document tree.
 
420
 
 
421
    .. WARNING:: Potentially dangerous; use with caution.
 
422
 
 
423
    Default: disabled (None).  Option: ``--strip-element-with-class``.
 
424
 
378
425
_`title`
379
426
    The document title as metadata, which does not become part of the
380
427
    document body.  It overrides a document-supplied title.  For
437
484
    ``--pep-references``.
438
485
 
439
486
_`pep_base_url`
440
 
    Base URL for PEP references.  
 
487
    Base URL for PEP references.
441
488
 
442
489
    Default: "http://www.python.org/peps/".  Option:
443
490
    ``--pep-base-url``.
444
491
 
 
492
_`pep_file_url_template`
 
493
    Template for PEP file part of URL, interpolated with the PEP
 
494
    number and appended to pep_base_url_.
 
495
 
 
496
    Default: "pep-%04d".  Option: ``--pep-file-url``.
 
497
 
445
498
_`raw_enabled`
446
499
    Enable or disable the "raw_" directive.  A "warning" system
447
500
    message (including the directive text) is inserted instead.  (See
457
510
    ``--rfc-references``.
458
511
 
459
512
_`rfc_base_url`
460
 
    Base URL for RFC references.  
 
513
    Base URL for RFC references.
461
514
 
462
515
    Default: "http://www.faqs.org/rfcs/".  Option: ``--rfc-base-url``.
463
516
 
509
562
[pep reader]
510
563
````````````
511
564
 
512
 
The `pep_references`_ and `rfc_references`_ options
 
565
The `pep_references`_ and `rfc_references`_ settings
513
566
(`[restructuredtext parser]`_) are set on by default.
514
567
 
515
568
 
675
728
 
676
729
    __ `stylesheet_path [latex2e writer]`_
677
730
 
 
731
_`template`
 
732
    Path to template file, which must be encoded in UTF-8 [#pwd]_.
 
733
 
 
734
    Default: "template.txt" in the docutils/writers/html4css1/
 
735
    directory (installed automatically; for the exact machine-specific
 
736
    path, use the ``--help`` option).  Options: ``--template``.
 
737
 
678
738
.. _xml_declaration [html4css1 writer]:
679
739
 
680
740
xml_declaration
698
758
"[html4css1 writer]" section of configuration files is processed
699
759
before the "[pep_html writer]" section.
700
760
 
701
 
The PEP/HTML Writer's default for the ``stylesheet_path`` setting
702
 
differs from that of the standard HTML Writer:
703
 
``docutils/writers/pep_html/pep.css`` in the installation directory is
704
 
used.  For the exact machine-specific path, use the ``--help`` option.
705
 
 
706
761
_`no_random`
707
762
    Do not use a random banner image.  Mainly used to get predictable
708
763
    results when testing.
715
770
 
716
771
    Default: current directory (".").  Options: ``--pep-home``.
717
772
 
718
 
_`template`
719
 
    Path to PEP template file [#pwd]_.
720
 
 
721
 
    Default: "pep-html-template" (in current directory).  Options:
722
 
    ``--template``.
723
 
 
724
773
_`python_home`
725
774
    Python's home URL.
726
775
 
727
776
    Default: parent directory ("..").  Options: ``--python-home``.
728
777
 
 
778
The PEP/HTML Writer's default for the following settings differ from
 
779
those of the standard HTML Writer:
 
780
 
 
781
* ``stylesheet_path``: The default is
 
782
  ``docutils/writers/pep_html/pep.css`` in the installation directory.
 
783
  For the exact machine-specific path, use the ``--help`` option.
 
784
 
 
785
* ``template``: The default is
 
786
  ``docutils/writers/pep_html/template.txt`` in the installation
 
787
  directory.  For the exact machine-specific path, use the ``--help``
 
788
  option.
 
789
 
729
790
 
730
791
[s5_html writer]
731
792
.................
735
796
"[html4css1 writer]" section of configuration files is processed
736
797
before the "[s5_html writer]" section.
737
798
 
738
 
The S5/HTML Writer's default for the ``compact_lists`` setting differs
739
 
from that of the standard HTML Writer: the default here is to disable
740
 
compact lists.
 
799
_`hidden_controls`
 
800
    Auto-hide the presentation controls in slideshow mode, or or keep
 
801
    them visible at all times.
 
802
 
 
803
    Default: auto-hide (1).  Options: ``--hidden-controls``,
 
804
    ``--visible-controls``.
741
805
 
742
806
_`current_slide`
743
 
 
744
807
    Enable or disable the current slide indicator ("1/15").
745
808
 
746
809
    Default: disabled (None).  Options: ``--current-slide``,
770
833
 
771
834
    Default: None.  Option: ``--theme-url``.
772
835
 
 
836
_`view_mode`
 
837
    The initial view mode, either "slideshow" or "outline".
 
838
 
 
839
    Default: "slidewhow".  Option: ``--view-mode``.
 
840
 
 
841
The S5/HTML Writer's default for the following settings differ
 
842
from those of the standard HTML Writer:
 
843
 
 
844
* ``compact_lists``: The default here is to disable compact lists.
 
845
 
 
846
* ``template``: The default is
 
847
  ``docutils/writers/s5_html/template.txt`` in the installation
 
848
  directory.  For the exact machine-specific path, use the ``--help``
 
849
  option.
 
850
 
773
851
 
774
852
[latex2e writer]
775
853
````````````````
876
954
    Enable or disable section ("." subsection ...) prefixes for
877
955
    compound enumerators.  This has no effect unless
878
956
    `compound_enumerators`_ are enabled.
879
 
    
 
957
 
880
958
    Default: disabled (None).  Options:
881
959
    ``--section-prefix-for-enumerators``,
882
960
    ``--no-section-prefix-for-enumerators``.
918
996
[buildhtml application]
919
997
```````````````````````
920
998
 
 
999
_`ignore`
 
1000
    List of wildcard (shell globing) patterns to silently ignore.  To
 
1001
    specify multiple patterns in configuration files, use
 
1002
    colon-separated patterns; on the command line, the option may be
 
1003
    used more than once.
 
1004
 
 
1005
    Default: ['.svn', 'CVS'].  Options: ``--ignore``.
 
1006
 
921
1007
_`prune`
922
1008
    List of directories not to process.  To specify multiple
923
1009
    directories in configuration files, use colon-separated paths; on
946
1032
Other Settings
947
1033
==============
948
1034
 
949
 
These settings are only effective as command-line options, positional
950
 
arguments, or for internal use; setting them in configuration files
951
 
has no effect.
 
1035
Command-Line Only
 
1036
-----------------
 
1037
 
 
1038
These settings are only effective as command-line options; setting
 
1039
them in configuration files has no effect.
952
1040
 
953
1041
_`config`
954
1042
    Path to a configuration file to read (if it exists) [#pwd]_.
962
1050
 
963
1051
    Default: None.  Options: ``--config``.
964
1052
 
 
1053
 
 
1054
Internal Settings
 
1055
-----------------
 
1056
 
 
1057
These settings are for internal use only; setting them in
 
1058
configuration files has no effect, and there are no corresponding
 
1059
command-line options.
 
1060
 
 
1061
_`_config_files`
 
1062
    List of paths of applied configuration files.
 
1063
 
 
1064
    Default: None.  No command-line options.
 
1065
 
965
1066
_`_directories`
966
1067
    (``buildhtml.py`` front end.)  List of paths to source
967
1068
    directories, set from positional arguments.
985
1086
 
986
1087
    Default: stdin (None).  No command-line options.
987
1088
 
 
1089
 
988
1090
.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
989
1091
 
990
1092
.. [#pwd] Path relative to the working directory of the process at
1009
1111
     (e.g. in PDF or DVI format) depends on.  Thus, images and
1010
1112
     stylesheets are both unconditionally recorded as dependencies
1011
1113
     when using the LaTeX writer.
1012
 
   
 
1114
 
1013
1115
.. [#footnote_space] The footnote space is trimmed if the reference
1014
1116
   style is "superscript", and it is left if the reference style is
1015
1117
   "brackets".