diff options
Diffstat (limited to 'doc/Makefile')
-rw-r--r-- | doc/Makefile | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..4c81dfc --- /dev/null +++ b/doc/Makefile | |||
@@ -0,0 +1,321 @@ | |||
1 | #Path to this subsystem's root directory | ||
2 | SUBSYSROOT := $(shell pwd) | ||
3 | |||
4 | # NOTE: MANIFESTHASH in manifest_conf.mk needs to be updated with final release tag before a release | ||
5 | # The manifest_conf.mk defines MANIFESTHASH and MANIFESTURL and PROFILE_NAME | ||
6 | include manifest_conf.mk | ||
7 | |||
8 | # An alternative is to clone the manifest repository and extract the list of target manifest files from that | ||
9 | # We need all to get all README, but only first in alphabetic list is used to extract info from poky/ | ||
10 | TARGETDEFAULTXMLS := p2041rdb/default.xml | ||
11 | |||
12 | |||
13 | # ***************** Generic docbuild.git auto-clone + s_docbuild symlink *** | ||
14 | # This also defines TMPCLONEROOT which optionally can be nondefault using BOOK_GLOBALCLONEROOT=yes or a path | ||
15 | include init.mk | ||
16 | |||
17 | # ****************** SUPPORT FOR TARGETS *************************** | ||
18 | PATH_TARGETS = $(SUBSYSROOT)/s_targets | ||
19 | #Git repositories to be cloned | ||
20 | NAME_TARGETS := targets | ||
21 | #Path to the directory under which repos shall be cloned. | ||
22 | DOCBASEDIR=$(shell pwd) | ||
23 | REPODIR=$(DOCBASEDIR)/.. | ||
24 | TMPCLONEROOT_TARGETS := $(TMPCLONEROOT)/$(NAME_TARGETS) | ||
25 | |||
26 | |||
27 | # ******************* AutoGenerated chapter from template and target READMEs ******* | ||
28 | BUILDBOOT_XML := book-enea-linux-release-info/doc/build_boot_generated.xml | ||
29 | BUILDBOOT_TEMPLATE := book-enea-linux-release-info/doc/build_boot_template.xml | ||
30 | |||
31 | PKGDIFF_GEN_XML := book-enea-linux-release-info/doc/pkgdiff_generated.xml | ||
32 | JIRA_ISSUES_GEN_XML := book-enea-linux-release-info/doc/jiraissues_generated.xml | ||
33 | |||
34 | |||
35 | # ----------------------------------------------------- | ||
36 | #Path to DocBook make files and templates | ||
37 | DOCBOOKMAKE = $(SUBSYSROOT)/s_docbuild/docmake | ||
38 | DOCBOOKTEMPLATE = $(SUBSYSROOT)/s_docbuild/template | ||
39 | |||
40 | #Path to the OLINK database including leading part of file name (will add -$(FORMAT).db) | ||
41 | DOCBOOKOLINKDB_BASE = $(SUBSYSROOT)/s_docbuild/olinkdb/olink-targetdb-master | ||
42 | |||
43 | DOCBOOK_OLINKS ?= yes | ||
44 | DOCBOOK_FO_USEFOP ?= yes | ||
45 | DOCBOOK_TO_BOOKDIR ?= yes | ||
46 | DOCBOOK_CLEANTMP ?= yes | ||
47 | |||
48 | #Components (books) in this subsystem. Now use all books found here | ||
49 | # COMPONENTS := book-enea-linux-release-info book-enea-linux-open-source | ||
50 | # COMPONENTS += book-enea-linux-eclipse-open-source | ||
51 | COMPONENTS := $(shell ls -d book-enea* ) | ||
52 | |||
53 | # -------------------------------------------------------------- | ||
54 | ifeq ($(VERBOSE),yes) | ||
55 | VERB := | ||
56 | else | ||
57 | VERB := @ | ||
58 | endif | ||
59 | MAKEFLAGS += --no-print-directory | ||
60 | MAKEFLAGS += --directory $(SUBSYSROOT) | ||
61 | MAKEFLAGS += --no-builtin-rules --no-builting-variables | ||
62 | |||
63 | # Skip xml validation to make it possible to include xml files with unresolved links | ||
64 | VALIDATE = no | ||
65 | |||
66 | # BL_LABEL is either given on make command line or using BOOK_VER which have defaults below or a timestamp | ||
67 | |||
68 | # ****************************************************************** | ||
69 | |||
70 | # Export all parameters including those on the command line | ||
71 | export | ||
72 | |||
73 | .PHONY: doc books docusage init initbuild inittargets initpardoc initbuildboot dist | ||
74 | |||
75 | |||
76 | docusage: | ||
77 | @echo 'make docusage #Shows this help text' | ||
78 | @echo ' DOCBOOK_TOOLS_VERSIONS=yes #Displays DocBook tools versions in this machine' | ||
79 | @echo 'make doc #Builds the userdoc, does autoinit if needed' | ||
80 | @echo 'make dist BOOK_DIST_DIR=xx/doc #Builds all and copies results to BOOK_DIST_DIR' | ||
81 | @echo ' #Does not work with DOCBOOK_TO_BOOKDIR or BOOK_BUILD_DIR' | ||
82 | @echo ' #Currently EclipseHelp formated doc will not be in BOOK_DIST_DIR' | ||
83 | @echo ' # unless BOOK_DIST_ECLIPSE is set to yes' | ||
84 | @echo 'make init #Init all needed init* below' | ||
85 | @echo 'make initbuild #Init s_docbuild Docbook build system and central files' | ||
86 | @echo 'make inittargets #Init s_targets using repo tool Targets in this distro with poky' | ||
87 | @echo 'make initpardoc #Init s_docsrc_common using info from poky/' | ||
88 | @echo 'make initbuildboot #Init build_boot chapter from READMEs and template in release info' | ||
89 | @echo ' DOCBOOK_CLEANTMP=no #Option to keep temp files in doc/ and tmp/' | ||
90 | @echo ' BOOK_GLOBALCLONEROOT=yes #Option for all init above to clone all outside the doc directory' | ||
91 | @echo ' BOOK_GLOBALCLONEROOT=otherpath #Option for all init above to clone all' | ||
92 | @echo 'make pullbuild #git pull in s_docbuild' | ||
93 | @echo 'make pulltargets #git pull in s_targets. You need also initpardoc initbuildboot' | ||
94 | @echo 'make clean #Clean. Also clean s_* but not any external clones' | ||
95 | @echo '' | ||
96 | @echo 'Optional parameters for make doc:' | ||
97 | @echo ' COMP=<book-directory> #Component (book) to build. Book component names are book-*' | ||
98 | @echo ' #Default component/s:' | ||
99 | @echo ' $(COMPONENTS)' | ||
100 | @echo ' FORMAT=<format> #One of: pdf, html, or eclipse (Default all are built)' | ||
101 | @echo ' BL_LABEL=<baseline> #Becomes footer in book (default: from poky enea.conf MAJORMINOR' | ||
102 | @echo ' # and with profile name taken from the manifest repo name)' | ||
103 | @echo ' DOCBOOK_TO_BOOKDIR=no #(default yes) Avoid moving result to book directory' | ||
104 | @echo ' # and avoid erasing common doc and tmp directories' | ||
105 | @echo ' BOOKFORCE=yes #Force rebuilding (ignore dependency on file times or BL_LABEL)' | ||
106 | @echo ' # Dependency only works if common doc directory is kept' | ||
107 | @echo ' BOOKCONDITION="xx;yy;.." #Include XML elements with condition any of xx or yy' | ||
108 | @echo ' # (if rebuilding, BOOKFORCE=yes may be needed)' | ||
109 | @echo ' # Empty=only default. none=none, all=everything.' | ||
110 | @echo ' BOOKDEFAULTCONDITION #Default conditions, if no BOOKCONDITION. Used in book-*/swcomp.mk' | ||
111 | @echo ' SHOW_COMMENTS=yes #For proofread. Unhide <remark>..</remark> comments Only PDF' | ||
112 | @echo ' BOOKVERBOSE=yes #Verbose info building books' | ||
113 | @echo ' DOCBOOK_OLINKS=no #Avoid the olink database in Makefile (in book not using it)' | ||
114 | @echo ' DOCBOOK_OLINK_TARGETDB=only #Build a target db for this book (for links into it)' | ||
115 | @echo ' DOCBOOK_OLINK_TARGETDB=yes #Build a target db AND build the book' | ||
116 | @echo ' #Master olinkdb defined in this Makefile, one per generated format, is:' | ||
117 | @echo ' $(DOCBOOKOLINKDB_BASE)_*.db' | ||
118 | @echo ' Typical examples:' | ||
119 | @echo ' make doc Creates all books, all formats' | ||
120 | @echo ' make doc COMP=book-xxxx FORMAT=html' | ||
121 | @echo ' make doc COMP=book-xxxx FORMAT=pdf' | ||
122 | @echo ' make doc BL_LABEL="Version 1.2.3" Creates all with version in footers and front' | ||
123 | |||
124 | @echo ' Requires docbook-xsl-1.76.1 or later, docbook-xml 4.2, svg1.1, fop-1.0 + fop-hyph.jar' | ||
125 | @echo ' fop + the separate fop-hyph can be found together in package "libfop-java"' | ||
126 | @echo ' otherwise fetch fop-hyph.jar and place in same place as fop.jar' | ||
127 | @echo ' Requires libxml2-2.7.8 or later, libxslt-1.1.26 or later' | ||
128 | @echo ' Requires java machine to run fop (creating PDF). jar for optional FORMAT=eclipse' | ||
129 | @echo ' Without jar, the optional EclipseHelp format can not be built' | ||
130 | @echo ' tools_book_standalone.mk => libxml2, libxslt, and fop (and to catalog-el.xml)' | ||
131 | @echo ' catalog-el.xml => svg, docbook-xml, docbook-xsl' | ||
132 | ifeq ($(DOCBOOK_TOOLS_VERSIONS),yes) | ||
133 | $(VERB)$(MAKE) -f $(DOCBOOKMAKE)/tools_book_standalone.mk book_tools_versions | ||
134 | endif | ||
135 | |||
136 | # We rely on make doing these in order left to right | ||
137 | init: initbuild inittargets initpardoc initbuildboot initpkgdiff initissues | ||
138 | pullall: pullbuild pulltargets | ||
139 | |||
140 | # If no COMP, iterate over books-* in COMPONENTS with make doc | ||
141 | ifeq ($(COMP),) | ||
142 | doc: | ||
143 | ifneq ($(filter book-%, $(COMPONENTS)),) | ||
144 | $(VERB)for comp in $(filter book-%, $(COMPONENTS)); do \ | ||
145 | $(MAKE) doc COMP=$$comp; \ | ||
146 | done | ||
147 | endif | ||
148 | |||
149 | else | ||
150 | include $(SUBSYSROOT)/$(COMP)/swcomp.mk | ||
151 | |||
152 | doc: books | ||
153 | @# | ||
154 | endif | ||
155 | |||
156 | dist: doc | ||
157 | @echo "Copying resulting built documents to $(BOOK_DIST_DIR)" | ||
158 | $(VERB)if [ "$(BOOK_DIST_DIR)" = "" ]; then echo "ERROR: Missing BOOK_DIST_DIR parameter, typically shall be xxx/doc"; exit 10; fi | ||
159 | $(VERB)if [ ! -d "`dirname $(BOOK_DIST_DIR)`" ]; then echo "ERROR: Missing parent for BOOK_DIST_DIR"; exit 10; fi | ||
160 | $(VERB)if [ -f "$(BOOK_DIST_DIR)/Makefile" ]; then echo "ERROR: Wrong BOOK_DIST_DIR, contains a Makefile?"; exit 10; fi | ||
161 | $(VERB)if [ ! -d "$(BOOK_DIST_DIR)" ]; then mkdir -p "$(BOOK_DIST_DIR)" ; fi | ||
162 | $(VERB)for book in $(COMPONENTS); do \ | ||
163 | if ls -d $$book/book*.pdf >/dev/null 2>&1; then cp --preserve=timestamps $$book/book*.pdf "$(BOOK_DIST_DIR)" ; fi ; \ | ||
164 | if ls -d $$book/html >/dev/null 2>&1; then cp -r --preserve=timestamps $$book/html "$(BOOK_DIST_DIR)" ; fi ; \ | ||
165 | if [ "$(BOOK_DIST_ECLIPSE)" = "yes" ]; then \ | ||
166 | if ls -d $$book/eclipse >/dev/null 2>&1; then cp -r --preserve=timestamps $$book/eclipse "$(BOOK_DIST_DIR)" ; fi ; \ | ||
167 | fi ; \ | ||
168 | done | ||
169 | |||
170 | # Default FORMATs | ||
171 | ifeq ($(FORMAT),) | ||
172 | FORMAT=html pdf eclipse | ||
173 | endif | ||
174 | |||
175 | |||
176 | books: init | ||
177 | # BOOKPACKAGES is defined in all book-*/swcomp.mk | ||
178 | $(VERB)DISTRO_VERSION_MAJOR=`egrep '"EneaLinux_DISTRO_VERSION_MAJOR"' s_docsrc_common/pardoc-distro.xml | sed 's/.*<phrase>//;s/<\/phrase>.*//'` ; \ | ||
179 | DISTRO_VERSION_MINOR=`egrep '"EneaLinux_DISTRO_VERSION_MINOR"' s_docsrc_common/pardoc-distro.xml | sed 's/.*<phrase>//;s/<\/phrase>.*//'` ; \ | ||
180 | BOOKVER="Profile $(PROFILE_NAME)-$$DISTRO_VERSION_MAJOR$$DISTRO_VERSION_MINOR" ; \ | ||
181 | for book in $(BOOKPACKAGES); do \ | ||
182 | for format in $(FORMAT); do \ | ||
183 | $(MAKE) -f $(DOCBOOKMAKE)/make_docbook_standalone.mk BOOK=$$book FORMAT=$$format BOOK_VER="$$BOOKVER" books || exit 10; \ | ||
184 | done ; \ | ||
185 | done | ||
186 | ifeq ($(DOCBOOK_TO_BOOKDIR),yes) | ||
187 | $(VERB)rm -rf doc tmp | ||
188 | else | ||
189 | ifeq ($(DOCBOOK_CLEANTMP),yes) | ||
190 | # keep only doc/pdf/book-*.pdf doc/eclipse/plugins/com.enea.doc.book-* but delete doc/eclipse/plugins/com.enea.doc.book-*/done* | ||
191 | $(VERB)rm -rf tmp 2>/dev/null ; rm -rf doc/pdf/book-*/ ; rm -rf doc/eclipse/plugins/com.enea.doc.book-*/done* 2>/dev/null | ||
192 | endif | ||
193 | endif | ||
194 | |||
195 | # cleaninit cleans ALL tmpcommon and all s_* and generated build_boot chapter xml | ||
196 | clean: cleaninit cleanbuildboot cleanpkgdiff cleanissues | ||
197 | $(VERB)rm -rf doc tmp 2>/dev/null | ||
198 | ifneq ($(filter book-%, $(COMPONENTS)),) | ||
199 | $(VERB)for comp in $(filter book-%, $(COMPONENTS)); do \ | ||
200 | rm -rf $$comp/book*.pdf $$comp/html $$comp/eclipse 2>/dev/null; \ | ||
201 | done | ||
202 | $(VERB)rm -rf doc tmp 2>/dev/null | ||
203 | endif | ||
204 | |||
205 | |||
206 | # ****************************************************************** | ||
207 | # ****************** SUPPORT FOR TARGETS *************************** | ||
208 | inittargets: s_targets | ||
209 | pulltargets: | ||
210 | $(VERB)if [ ! -d s_targets ]; then echo "ERROR: No s_targets exists?" ; exit 10 ; fi | ||
211 | $(VERB)cd s_targets; for targ in *; do ( cd $targ ; git pull ) | ||
212 | |||
213 | |||
214 | # ----------------------------------------- | ||
215 | |||
216 | # Use repo to auto-clone each target separately - VERY LARGE if there are many targets (5 targets => about 1.3 Gytes) | ||
217 | |||
218 | s_targets: $(TMPCLONEROOT_TARGETS) | ||
219 | $(VERB)rm s_targets 2>/dev/null; ln -s $(TMPCLONEROOT_TARGETS) s_targets | ||
220 | |||
221 | |||
222 | $(TMPCLONEROOT_TARGETS): | ||
223 | $(VERB)if [ ! -d "$(TMPCLONEROOT)" ] ; then mkdir -p "$(TMPCLONEROOT)" ; fi | ||
224 | $(VERB)if [ ! -d $(TMPCLONEROOT_TARGETS) ]; then mkdir -p $(TMPCLONEROOT_TARGETS) ; fi | ||
225 | @echo "**** Cloning all targets using repo tool into $(TMPCLONEROOT_TARGETS)" | ||
226 | @echo "TARGETDEFAULTXMLS is <$(TARGETDEFAULTXMLS)>" | ||
227 | $(VERB)for target_default_xml in $(TARGETDEFAULTXMLS); \ | ||
228 | do \ | ||
229 | TARGDIR=$(TMPCLONEROOT_TARGETS)/`dirname $$target_default_xml` ; \ | ||
230 | echo "TARGDIR=<$$TARGDIR>" ; \ | ||
231 | if [ ! -d $$TARGDIR ]; then mkdir -p $$TARGDIR ; fi ; \ | ||
232 | ( cd $$TARGDIR ; \ | ||
233 | echo "*** Doing repo init -u $(MANIFESTURL) -b $(MANIFESTHASH) -m $$target_default_xml ; repo sync"; \ | ||
234 | repo init -u $(MANIFESTURL) -b $(MANIFESTHASH) -m $$target_default_xml ; repo sync ; \ | ||
235 | ) ; \ | ||
236 | done | ||
237 | |||
238 | # **************************************************************************** | ||
239 | # ******************** SUPPORT FOR dynamic pardoc with added parameters ****** | ||
240 | # pardoc-distro can contain MAJOR.MINOR-xxxxx keeping -xxxx when replacing MINOR.MINOR from enea.conf | ||
241 | |||
242 | PATH_DOCSRC_COMMON = $(SUBSYSROOT)/s_docsrc_common | ||
243 | NAME_DOCSRC_COMMON = docsrc_common | ||
244 | TMPCLONEROOT_DOCSRC_COMMON := $(TMPCLONEROOT)/$(NAME_DOCSRC_COMMON) | ||
245 | TMPPARDOC := $(TMPCLONEROOT_DOCSRC_COMMON)/pardoc-distro.xml | ||
246 | |||
247 | initpardoc: s_docsrc_common | ||
248 | |||
249 | cleanpardoc: | ||
250 | $(VERB)rm -rf $(TMPCLONEROOT_DOCSRC_COMMON) ; rm s_docsrc_common | ||
251 | |||
252 | s_docsrc_common: $(TMPCLONEROOT_DOCSRC_COMMON) | ||
253 | $(VERB)rm s_docsrc_common 2>/dev/null; ln -s $(TMPCLONEROOT_DOCSRC_COMMON) s_docsrc_common | ||
254 | |||
255 | $(TMPCLONEROOT_DOCSRC_COMMON): s_targets | ||
256 | $(VERB)if [ ! -d "$(TMPCLONEROOT)" ] ; then mkdir -p "$(TMPCLONEROOT)" ; fi | ||
257 | $(VERB)if [ ! -d $(TMPCLONEROOT_DOCSRC_COMMON) ]; then mkdir -p $(TMPCLONEROOT_DOCSRC_COMMON) ; fi | ||
258 | @echo "**** Copy and patch docsrc_common/ files to $(TMPCLONEROOT_DOCSRC_COMMON)" | ||
259 | @echo "*** Add parameters from first target's enea.conf and add manifest parameters" | ||
260 | $(VERB)FIRSTTARGET=`ls -1 s_targets/ | head -1`; \ | ||
261 | ENEACONF=s_targets/$$FIRSTTARGET/poky/meta-el-common/conf/distro/enea.conf ; \ | ||
262 | DISTRO_VERSION_MAJOR=`egrep '^DISTRO_VERSION_MAJOR' $$ENEACONF | sed 's/^[^"]*"//;s/".*//'` ; \ | ||
263 | DISTRO_VERSION_MINOR=`egrep '^DISTRO_VERSION_MINOR' $$ENEACONF | sed 's/^[^"]*"//;s/".*//'` ; \ | ||
264 | cat docsrc_common/pardoc-distro.xml | sed '/<\/section>/d' | \ | ||
265 | sed '/<!ENTITY ENEA_LINUX_REL_VER/s/MAJOR.MINOR/'"$$DISTRO_VERSION_MAJOR$$DISTRO_VERSION_MINOR"'/' | \ | ||
266 | sed '/<!ENTITY . common_poky_entities SYSTEM/s/s_targets\/[^\/]*\/poky/s_targets\/'"$$FIRSTTARGET"'\/poky/' >$(TMPPARDOC) ; \ | ||
267 | echo "<para id=\"EneaLinux_DISTRO_VERSION_MAJOR\"><phrase>$$DISTRO_VERSION_MAJOR</phrase></para>" >>$(TMPPARDOC) ; \ | ||
268 | echo "<para id=\"EneaLinux_DISTRO_VERSION_MINOR\"><phrase>$$DISTRO_VERSION_MINOR</phrase></para>" >>$(TMPPARDOC) ; \ | ||
269 | echo "<para id=\"EneaLinux_PROFILE_NAME\"><phrase>$(PROFILE_NAME)</phrase></para>" >>$(TMPPARDOC) ; \ | ||
270 | echo "<para id=\"EneaLinux_MANIFESTURL\"><phrase>$(MANIFESTURL)</phrase></para>" >>$(TMPPARDOC) ; \ | ||
271 | echo "<para id=\"EneaLinux_MANIFESTHASH\"><phrase>$(MANIFESTHASH)</phrase></para>" >>$(TMPPARDOC) ; \ | ||
272 | echo "</section>" >>$(TMPPARDOC) | ||
273 | |||
274 | # **************************************************************************** | ||
275 | # ***** Create XML chapter with build/boot commands from all README files in s_targets | ||
276 | |||
277 | initbuildboot: $(BUILDBOOT_XML) | ||
278 | |||
279 | cleanbuildboot: | ||
280 | $(VERB)rm -f $(BUILDBOOT_XML) 2>/dev/null | ||
281 | |||
282 | |||
283 | $(BUILDBOOT_XML): s_targets $(BUILDBOOT_TEMPLATE) | ||
284 | @echo "**** Creating $(BUILDBOOT_XML) from READMEs" | ||
285 | $(VERB)INITBB_CMD=initbuildboot.sh ; \ | ||
286 | if [ -f "$$INITBB_CMD" ]; then \ | ||
287 | sh "$$INITBB_CMD" -xml $(BUILDBOOT_XML) -template $(BUILDBOOT_TEMPLATE) ; \ | ||
288 | else \ | ||
289 | echo "ERROR: Missing $$INITBB_CMD, can not create $(BUILDBOOT_XML)"; exit 10; \ | ||
290 | fi | ||
291 | |||
292 | # **************************************************************************** | ||
293 | # ***** Create Package DIFF XML section | ||
294 | |||
295 | initpkgdiff: $(PKGDIFF_GEN_XML) | ||
296 | |||
297 | cleanpkgdiff: | ||
298 | $(VERB)rm -f $(PKGDIFF_GEN_XML) 2>/dev/null | ||
299 | |||
300 | $(PKGDIFF_GEN_XML): | ||
301 | $(VERB)PREVIOUS_BL=`egrep '"prev_baseline"' docsrc_common/pardoc-distro.xml | sed 's/^.*<phrase>//;s/<\/phrase>.*$$//'` ; \ | ||
302 | echo "**** Generating $(PKGDIFF_GEN_XML) compared to $$PREVIOUS_BL, using gen_pkgdiff.py" ; \ | ||
303 | python gen_pkgdiff.py >$(PKGDIFF_GEN_XML) | ||
304 | |||
305 | |||
306 | # **************************************************************************** | ||
307 | # ***** Create Jira Issues XML section for the known bugs chapter | ||
308 | |||
309 | .PHONY: $(JIRA_ISSUES_GEN_XML) | ||
310 | # We want new issue list to be generated also at build, not only at init | ||
311 | |||
312 | initissues: $(JIRA_ISSUES_GEN_XML) | ||
313 | |||
314 | cleanissues: | ||
315 | $(VERB)rm -f $(JIRA_ISSUES_GEN_XML) 2>/dev/null | ||
316 | |||
317 | $(JIRA_ISSUES_GEN_XML): | ||
318 | @echo "**** Generating $(JIRA_ISSUES_GEN_XML), fetching from Jira using gen_known_issues.py" | ||
319 | $(VERB)python gen_known_issues.py >$(JIRA_ISSUES_GEN_XML) | ||
320 | |||
321 | # **************************************************************************** | ||