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
|
<?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 appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>
<appendix id="app.daps.user.migrate">
<title>Migrating Existing DocBook Projects</title>
<para>
This section provides instructions on how to migrate existing DocBook
projects so that you can use &dapsacr; for managing and publishing them.
</para>
<procedure id="pro.daps.user.migrate">
<title>Making DocBook Projects Compatible with &dapsacr;</title>
<step>
<para>
If your XML files are distributed across several subdirectories, flatten
the hierarchy <remark>dpopov 2016-10-12: this requires an
explanation</remark> and put all XML files directly into the
<filename>xml</filename> subdirectory that is required by &dapsacr;. See
<xref linkend="ex.daps.dir.doc" xrefstyle="select:title"/>. Hosting
multiple documentation projects in the same <filename>xml</filename>
directory is fine as long as the file names are unique. You can put
multiple &main; files there.
</para>
</step>
<step>
<para>
If you have any XIncludes or entity declaration files, also put them
into the <filename>xml</filename> subdirectory.
</para>
</step>
<step>
<para>
Depending on the file type of your source images, add them to the
respective subdirectories in
<filename><replaceable>YOUR_DOC_DIR</replaceable>/images/src</filename>.
The <filename>image</filename> directory and its substructure is
required by &dapsacr;. For details, refer to
<xref linkend="ex.daps.dir.doc" xrefstyle="select:title"/>.
</para>
</step>
<step>
<para>
Make sure that the base names of your image files are unique. For
details, refer to <xref linkend="sec.daps.user.imgs.req"/>.
</para>
</step>
<step>
<para>
Adjust all references of image files, XIncludes, and entity
declarations, in the existing XML files to match the structure required
by &dapsacr;. The references must not include any absolute or relative
path, the plain file name is enough.
<remark>taroth 2012-04-12: maybe add examples for
image names, XIncludes and entity-decl? see commented section
below</remark>
</para>
</step>
<step>
<para>
Create a &dclong; file for each deliverable (book, article, set) that you want to generate from
your XML files. For more information, refer to
<xref linkend="sec.daps.user.basics.files"/>. Find a template for &dc;
files in your installed system in
<filename>/usr/share/daps/init_templates/&dc;-file.template</filename>.
</para>
</step>
</procedure>
<!-- fs 2016-06-10:
No longer needed
<para>
If you have already used &dapsacr;' predecessor
<literal>susedoc</literal>, use the
<filename>/usr/bin/daps-envconvert</filename> script for migrating your
ENV files to &dc; files. For a short overview of the main changes, refer
to
<filename>/usr/share/doc/packages/daps/README.upgrade_from_susedoc_4.x</filename>.
In contrast to susedoc, &dapsacr; uses the DocBook layout by default. The
&suse; stylesheets have been moved to a separate package,
<systemitem class="resource">suse-xsl-stylesheets</systemitem>. It is
available from the &suse-dapsrepo; repository. If you want to continue
using the &suse;-layout for your documentation projects, install this
package in addition to &dapsacr;. To make &dapsacr; use the &suse; layout,
adjust the <parameter>STYLEROOT</parameter> parameter in the &dc; files of
your documentation projects.
</para>
-->
</appendix>
|
