File: README

package info (click to toggle)
gwyddion 2.57-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 48,860 kB
  • sloc: ansic: 405,916; python: 7,867; sh: 5,241; makefile: 4,507; xml: 3,786; cpp: 2,572; pascal: 418; perl: 154; ruby: 130
file content (97 lines) | stat: -rw-r--r-- 2,849 bytes parent folder | download | duplicates (7)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

Contents:
0. Using devhelp
1. Building documentation
2. Custom scripts
3. Makefile rules
4. Cruft

===[ 0. Using devhelp ]======================================================

If you install Gwyddion to a system directory, its API documentation should
appear in the table of contents automatically.  To find documentation in a
nonstandard location, let's assume $HOME/opt/gwyddion, do either:

  export DEVHELP_SEARCH_PATH=$HOME/opt/gwyddion/share/gtk-doc/html

or

  mkdir -p ~/.devhelp/books
  cd ~/.devhelp/books
  for x in $HOME/opt/gwyddion/share/gtk-doc/html/*; do ln -s $x .; done

To integrate devehelp to vim, define

  function! DevHelpCurrentWord()
      let word = expand("<cword>")
      exe "!devhelp -s " . word
  endfunction

and map

  :call DevHelpCurrentWord<cr>

to a keystroke of your choice.


===[ 1. Building documentation ]=============================================

Building docs takes too much time, they are not built automatically whenever
source code changes.  If gtk-doc is found the documentation rebuild rules are
only enabled, not executed.  Change to the appropriate dir and run

  make docs

if you want to update the API documentation.


===[ 2. Custom scripts ]=====================================================

Almost everything is generated, pay attention as other gtk-doc employing
projects often let humans maintain much more files.  The ONLY human-edited
files are:

- libgwy*-docs.sgml (driver files)
- libgwy*.overrides (symbol overrides)
- content files (optional)
- Makefile templates

The rest is generated:

- libgwy*.types (supported by gtk-doc since 1.8)

- libgwy*-sections.txt (supported by gtk-doc since 1.8)
  rationale: if header files are organized reasonably they naturaly form
             sections, therefore sections created by gtkdoc-scan are directly
             used
  tools: add-objects.py adds GwyFoo and GwyFooClass to appropriate sections
         for classed types (using libgwy*.hierarchy as class list)

- template/*
  rationale: the usual approach when these files are partially generated and
             partially human-edited is a source of neverending revision
             management pain, therefore *all* section documentation is in the
             source code
  this directory is usually called tmpl, but it confused CVS if it was kept
  after removal


===[ 3. Makefile rules ]=====================================================

gtk-doc.mk are universal rules to be included in every documentation
Makefile.am.


===[ 4. Cruft ]==============================================================

gtk-doc scan may place a slightly broken doctype declaration to
MODULE-docs.sgml

  <!doctype book PUBLIC "-//DavenPort//DTD DocBook V3.0//EN" [

fix it to

  <!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [

or else you'll get really weird errors.