← Back to branch summary

~ubuntu-branches/ubuntu/trusty/krb5/trusty-proposed

« back to all changes in this revision

Viewing changes to doc/README

  • Committer: Package Import Robot
  • Author(s): Dmitrijs Ledkovs
  • Date: 2013-11-10 02:20:12 UTC
  • mfrom: (53.1.3 trusty-proposed)
  • Revision ID: package-import@ubuntu.com-20131110022012-b8ojkqhcxos55kln
Add alternate dependency on libverto-libevent1 as that's the package
ABI name in ubuntu.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/README
 
1
HTML
 
2
====
 
3
 
 
4
To build the documentation as HTML pages run:
 
5
 
 
6
sphinx-build source_dir  destination_dir
 
7
 
 
8
where
 
9
source_dir is the source directory which includes configuration file conf.py and all source files;
 
10
destination_dir is the directory for the built documentation.
 
11
 
 
12
Once completed, the newly generated HTML documentation can be viewed from the browser by pointing to destination_dir/index.html
 
13
 
 
14
 
 
15
MAN PAGES
 
16
=========
 
17
 
 
18
Similarly, to build the documentation as man pages run:
 
19
 
 
20
sphinx-build -b man source_dir  destination_dir
 
21
 
 
22
The list of manual pages to be built should be constructed under man_pages section on conf.py
 
23
 
 
24
 
 
25
CONVENTIONS
 
26
===========
 
27
 
 
28
We use the following conventions:
 
29
 
 
30
* Use four-space indentation where indentation levels are arbitrary.
 
31
  Do not use tabs anywhere.  Avoid trailing whitespace at the end of
 
32
  lines or files.
 
33
 
 
34
* Fill lines to 70 columns (the emacs default) where lines can be
 
35
  wrapped.
 
36
 
 
37
* For section headers, use === underlines for page titles, --- for
 
38
  sections, ~~~ for subsections, and ### for sub-subsections.  Make
 
39
  underlines exactly as long as titles.  Do not include trailing
 
40
  punctuation in section headers.  Do not capitalize section headers
 
41
  (except for the first word) except in source files intended to
 
42
  generate man pages.
 
43
 
 
44
* For bullet lists, use * for top-level bullets and - for sub-bullets.
 
45
  Do not indent bullet or enumerated lists relative to the surrounding
 
46
  text.
 
47
 
 
48
* Use italics (*word*) for words representing variables or parameters.
 
49
  Use boldface (**word**) for command options, subcommands of programs
 
50
  like kadmin, and krb5.conf/kdc.conf parameter names.  Use literal
 
51
  text (``text``) for examples and multi-component pathnames.  For
 
52
  command names, single-component filenames, and krb5.conf/kdc.conf
 
53
  section names, use references (like :ref:`kadmin(1)`) if introducing
 
54
  them, or just use them unadorned otherwise.
 
55
 
 
56
* In man pages for commands with subcommands, make a subsection for
 
57
  each subcommand.  Start the subcommand with an indented synopsis,
 
58
  then follow with non-indented text describing the subcommand and its
 
59
  options.  See kadmin_local.rst for an example.
 
60
 
 
61
* In man page synopses, put a newline in the RST source before each
 
62
  option.  Put all parts of the synopsis at the same indentation
 
63
  level.  Ideally we would want a hanging indent to the width of the
 
64
  command or subcommand name, but RST doesn't support that.  Use
 
65
  boldface for literal text in the synopsis, italics for variable
 
66
  text, and unadorned text for syntax symbols (such as square brackets
 
67
  to indicate optional parameters).  If immediately following one kind
 
68
  of inline markup with another or putting inline markup next to
 
69
  punctuation, you may need to use "\ " as a dummy separator.
 
70
 
 
71
* For directives that take a content block (e.g., note, error, and
 
72
  warning), leave a blank line before the content block (after any
 
73
  arguments or options that may be present).