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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet
href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
type="text/xml"
title="Profiling step"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>
<chapter id="cha.daps.user.trouble">
<title>Troubleshooting</title>
<abstract>
<para>
This chapter lists common problems and possible solutions, sorted into
categories. </para>
</abstract>
<remark>taroth 2012-12-12: todo - for FOP installation, mention download from
offo.sourceforeg.net in troubleshooting section and add xref</remark>
<!-- <qandaset><title>Installation and First Steps</title>
<qandaentry>
<question>
<para><remark>taroth 2012-06-01: FIXME</remark></para>
</question>
<answer/>
</qandaentry>
</qandaset>
-->
<qandaset id="qa.daps.user.trouble.output">
<title>Generating Output</title>
<qandaentry>
<question>
<para>Profiling does not work as expected?</para>
</question>
<answer>
<procedure>
<step>
<para> Check the values of your profiling attributes in the XML files:
They must use consistent spelling throughout a documentation project. If
you assigned multiple values to a profiling attribute, check if the
values are separated with a semicolon, for example,
<literal>os="linux;unix"</literal>. </para>
</step>
<step>
<para> Check the &dc; file for your documentation project: Does it
contain one or multiple <parameter>PROF*</parameter> parameters?
Otherwise &dapsacr; does not know which profiling attributes to
interpret. Do the <parameter>PROF*</parameter> parameters match the
profiling attributes used in the XML files? Do the values of the
<parameter>PROF*</parameter> parameters match the attribute values used
in the XML files? </para>
</step>
<step>
<para> Check the &main; file of your documentation projects: Does its
header contain the following line? </para>
<screen>href="urn:x-daps:xslt:profiling:docbook45-profile.xsl" type="text/xml"</screen>
<para> If not, any profiling parameters in the &dc; file will be
ignored during generation of the output. </para>
</step>
</procedure>
<para> For more details, refer to <xref linkend="sec.daps.user.edit.profile"
/> and <ulink url="http://www.sagehill.net/docbookxsl/Profiling.html"/>.
</para>
</answer>
</qandaentry>
</qandaset>
<qandaset id="qa.daps.user.trouble.misc">
<title>Miscellaneous</title>
<qandaentry id="qa.daps.user.trouble.misc.verbosity">
<question>
<para>Why does &dapsacr; not talk to me? <remark>dpopov 2016-10-12: Why don't &dapsacr; give me any feedback?</remark>
</para>
</question>
<answer>
<para>By default &dapsacr; only shows the result of the current subcommand.
To increase the verbosity run <command>daps</command> with the option
<option>-v</option>, <option>-vv</option>, or <option>-vvv</option>.
For the highest verbosity, use the <option>--debug</option> option. </para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Where do I find the log files?</para>
</question>
<answer>
<para> If you run into problems with &dapsacr; that you cannot
classify, check the &dapsacr; log files in
<filename><replaceable>YOUR_DOC_DIR</replaceable>/build/<replaceable>BOOKNAME</replaceable>/log</filename>.
A complete log file of the latest
<command>daps <replaceable>subcommand</replaceable> </command>
that was executed is available in <filename><replaceable>YOUR_DOC_DIR</replaceable>/build/<replaceable>BOOKNAME</replaceable>/log/make_<replaceable>SUBCOMMAND</replaceable>.log</filename>
</para>
<para> In case of an error the complete log file will be shown on the screen
(STDOUT). </para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Are all changes to &dapsacr; backward-compatible?</para>
</question>
<answer>
<para>
No. If you have recently updated to a higher &dapsacr; version and
afterward experience strange behavior that are difficult to debug, check
your custom &dapsacr; configuration file (&dapsconf-user;) against the
system-wide configuration file (&dapsconf-sys;). Search for any
parameters that may have changed. By default, the settings in the custom
&dapsacr; configuration file will override the settings in
&dapsconf-sys;. Therefore any parameter incompatibilities between the
files may lead to unexpected behavior of &dapsacr;.
</para>
<para>
When switching from &dapsacr; 1.x to &dapsacr; &dapsversion;, especially
check the syntax of any XSLT parameters that you are using (on the
command line, in scripts or in &dc; files). If you have not adjusted the
parameters to the new syntax, this may result in strange error messages.
For details, refer to <xref linkend="cha.daps.user.config"/>.
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>
|
