From: Michael Smith Date: Fri, 8 Apr 2005 02:41:59 +0000 (+0000) Subject: Added standard distro files, to make life easier for packagers; X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=38f83c3637def33f8f1f6f7a0442dafc6a4e5cbf;p=docbook-dsssl Added standard distro files, to make life easier for packagers; From README, moved copyright info to COPYING and install info to INSTALL. README content is not just minimal how-to info. Added BUGS and TODO, which are just pointers to SF trackers. Added AUTHORS just for sake completeness. --- diff --git a/website/AUTHORS b/website/AUTHORS new file mode 100644 index 000000000..6da05a5a6 --- /dev/null +++ b/website/AUTHORS @@ -0,0 +1,2 @@ +DocBook Website is maintained by Norman Walsh, , +and members of the DocBook Project, diff --git a/website/BUGS b/website/BUGS new file mode 100644 index 000000000..ad46d7761 --- /dev/null +++ b/website/BUGS @@ -0,0 +1,4 @@ +For information about open DocBook Website bugs, see the +following: + + http://sourceforge.net/tracker/?atid=384108&group_id=21935&func=browse diff --git a/website/COPYING b/website/COPYING new file mode 100644 index 000000000..2f7ecceae --- /dev/null +++ b/website/COPYING @@ -0,0 +1,68 @@ + +Copyright +--------- + +Copyright (C) 1999 - 2005 Norman Walsh + +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the ``Software''), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or +sell copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +Except as contained in this notice, the names of individuals +credited with contribution to this software shall not be used in +advertising or otherwise to promote the sale, use or other +dealings in this Software without prior written authorization +from the individuals in question. + +Any stylesheet derived from this Software that is publically +distributed will be identified with a different name and the +version strings in any derived Software will be changed so that +no possibility of confusion between the derived package and this +Software will exist. + +You may distribute this software under the same terms as DocBook. +This software is a customization of the DocBook XML V4.1.2, which +is governed by the following copyright: + + [DocBook is] Copyright 1992, 1993, 1994, 1995, 1996, 1998, + 1999 HaL Computer Systems, Inc., O'Reilly & Associates, Inc., + ArborText, Inc., Fujitsu Software Corporation, and the + Organization for the Advancement of Structured Information + Standards (OASIS). + + Permission to use, copy, modify and distribute the DocBook + DTD and its accompanying documentation for any purpose and + without fee is hereby granted in perpetuity, provided that + the above copyright notice and this paragraph appear in all + copies. The copyright holders make no representation about + the suitability of the DTD for any purpose. It is provided + "as is" without expressed or implied warranty. + +For more information about the DocBook DTD, see +http://www.oasis-open.org/docbook/ + +Warranty +-------- + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER +CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +Contacting the Author +--------------------- + +DocBook Website is maintained by Norman Walsh, , +and members of the DocBook Project, diff --git a/website/INSTALL b/website/INSTALL new file mode 100644 index 000000000..e8d85c62b --- /dev/null +++ b/website/INSTALL @@ -0,0 +1,25 @@ +$Id$ + +INSTALL file for the DocBook Website distribution + +---------------------------------------------------------------------- +DTD installation +---------------------------------------------------------------------- +Place the DTD files included in this distribution somewhere on +your system. Adjust your XML and SGML catalog(s), if appropriate, +such that they can find the included catalog.xml file. + +---------------------------------------------------------------------- +RELAX NG schema installation +---------------------------------------------------------------------- +Place the *.rnc and *.rng files included in this distribution +somewhere on your system. Adjust your schema locating rules, if +appropriate, such that they can find the included +locatingrules.xml file. + +---------------------------------------------------------------------- +XSL stylesheet installation +---------------------------------------------------------------------- +Place the XSL files in this distribution somewhere on your +system. Adjust your XML and SGML catalog(s), if appropriate, such +that they can find the included catalog.xml file. diff --git a/website/README b/website/README index 7277ebcb2..4ebf2220a 100644 --- a/website/README +++ b/website/README @@ -1,105 +1,151 @@ +$Id$ + README for the DocBook Website distribution -Website is an XML DTD and XSL stylesheet collection -for building, er, web sites. +Website is an XML DTD and XSL stylesheet collection for building, +er, web sites. + +For installation information, see the INSTALL file. This README +file provides some minimal documentation on authoring, validating, +and transforming Website documents. + +---------------------------------------------------------------------- +Website how-to guides +---------------------------------------------------------------------- +For more complete how-to information, see the following: -DTD Installation ----------------- + Website chapter in Bob Stayton's "DocBook XSL: The Complete Guide + http://sagehill.net/docbookxsl/Website.html -Place the files in this distribution somewhere on your machine. Adjust -your catalog(s) if appropriate (XML tools frequently do not support -catalogs, so this may be irrelevant for you). + Website example + http://docbook.sourceforge.net/release/website/current/example/ -Please use the following formal public identifier to identify this DTD: +The Website example is also in the example/ subdirectory in the +Website distribution (which may have been renamed to "examples" if +you have installed Website from a package via the +package-management system for your OS). - "-//Norman Walsh//DTD Website V2.5.0//EN" +---------------------------------------------------------------------- +Authoring and validating with DTDs (website.dtd or website-full.dtd) +---------------------------------------------------------------------- +To do DTD-driven authoring and validation of DocBook Website +documents, add a DOCTYPE to your documents using either a PUBLIC +or SYSTEM ID with the appropriate URI for either the included +website.dtd (based on Simplified DocBook) or website-full.dtd +(based on full DocBook) DTDs. For example: - - -XSL Installation ----------------- - -Place the XSL files in this distribution somewhere on your machine. - -Update the included catalog.xml file to point to a local -version of the stock DocBook XSL distribution, of which website -is a customization. - -Use ---- - -There are several ways to process the website XML files to produce an -HTML website. - -For more detailed instructions, see example/index.html or -http://docbook.sourceforge.net/release/website/2.4.0/example/ - -Copyright ---------- - -Copyright (C) 1999 - 2005 Norman Walsh - -Permission is hereby granted, free of charge, to any person -obtaining a copy of this software and associated documentation -files (the ``Software''), to deal in the Software without -restriction, including without limitation the rights to use, -copy, modify, merge, publish, distribute, sublicense, and/or -sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following -conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -Except as contained in this notice, the names of individuals -credited with contribution to this software shall not be used in -advertising or otherwise to promote the sale, use or other -dealings in this Software without prior written authorization -from the individuals in question. - -Any stylesheet derived from this Software that is publically -distributed will be identified with a different name and the -version strings in any derived Software will be changed so that -no possibility of confusion between the derived package and this -Software will exist. - -You may distribute this software under the same terms as DocBook. -This software is a customization of the DocBook XML V4.1.2, which -is governed by the following copyright: - - [DocBook is] Copyright 1992, 1993, 1994, 1995, 1996, 1998, - 1999 HaL Computer Systems, Inc., O'Reilly & Associates, Inc., - ArborText, Inc., Fujitsu Software Corporation, and the - Organization for the Advancement of Structured Information - Standards (OASIS). - - Permission to use, copy, modify and distribute the DocBook - DTD and its accompanying documentation for any purpose and - without fee is hereby granted in perpetuity, provided that - the above copyright notice and this paragraph appear in all - copies. The copyright holders make no representation about - the suitability of the DTD for any purpose. It is provided - "as is" without expressed or implied warranty. - -For more information about the DocBook DTD, see -http://www.oasis-open.org/docbook/ - -Warranty --------- - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES -OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER -CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. - -Contacting the Author ---------------------- - -This DTD is maintained by Norman Walsh, . + + +IMPORTANT: The example above may not be up-to-date. For the + current PUBLIC ID and URI see the actual website.dtd + and website-full.dtd files. + +---------------------------------------------------------------------- +Authoring with RELAX NG (website.rnc and website-full.rnc) +---------------------------------------------------------------------- +To do RNC-driven authoring of DocBook Website content with a +"RELAX NG aware" XML editing application such as oXygen XML +Editor, point your editing application at the included website.rnc +(based on Simplified DocBook) or website-full.rnc (based on full +DocBook) schema files. + +Alternatively, if you are authoring with an editor, such as +Emacs/nXML mode, that supports schema "locating rules", use the +included locatingrules.xml file. It tells your editor to +automatically associate any documents whose root element is +"webpage" (DocBook Website documents), with (by default) the +website.rnc schema. To have "webpage" documents instead associated +with the website-full.rnc, edit the locatingrules.xml file. + +To use the locating-rules.xml file with Emacs/nXML mode, either + + - do M-x customize-variable rng-schema-locating-files and then + add the absolute path to the locatingrules.xml file there + + OR + + - put the following into your .emacs file: + + (setq rng-schema-locating-files + (append + '("~/docbook-website/locatingrules.xml"))) + + Of course, replace the ~/docbook-website/locatingrules.xml + pathname with the appropriate location for your system. + +---------------------------------------------------------------------- +Validating with RELAX NG (website.rnc and website-full.rnc) +---------------------------------------------------------------------- +To validate Website documents using RELAX NG, do either of the +following: + + 1. Use RNV[1]; for example: + + rnv ~/docbook-website/website.rnc foo.xml + + 2. Use the xmllint tool from libxml2[1]; for example: + + xmllint --noout --relaxng ~/docbook-website/website.rng foo.xml + + IMPORTANT: If you use xmllint, you need to validate against + the *.rng versions of the schemas, not the *.rnc + versions. + +[1] http://davidashen.net/rnv.html +[2] http://xmlsoft.org/ + +---------------------------------------------------------------------- +Transforming your Website documents to HTML +---------------------------------------------------------------------- +Generating a website from your DocBook Website XML sources is a +multi-step process. The details are beyond the scope of this +README. For complete information, see the "Website how-to guides" +section at the beginning of this README. + +You can learn a lot by looking through the Makefile-example.txt +file included in the example/ directory. That is the actual +Makefile that was used, during the build of this distribution, to +generate the HTML output in the example/ directory. + +You can re-generate the output in the examples directory using the +following steps. + +1. Copy the example/ directory to another location (so that you + don't overwrite the original) and then change to that location. + + cp -pR /foo/docbook-website/example /tmp + cd /tmp/example + +2. Rename the Makefile-example.txt file to "Makefile". + + mv Makefile-example.txt Makefile + +3. Examine the Makefile and change the values of the following + variables as needed. + + DOCBOOK_WEBSITE + XSLT + XMLPARSER + +4. Clean out the existing HTML output. + + make clean + +5. Re-generate the HTML output. + + make + + That will build the default "tabular" version of the site. + +6. Optionally, you can also: + + * generate the alternative "non-tabular" version of the site + * post-process all of the HTML content with 'tidy' + + The easiest way to do those things is to feed 'make' some + variables on the command line: + + make USETIDY=1 MAKENONTAB=1 diff --git a/website/TODO b/website/TODO new file mode 100644 index 000000000..10532c493 --- /dev/null +++ b/website/TODO @@ -0,0 +1,4 @@ +For information about pending DocBook Website feature requests, +see the following: + + http://sourceforge.net/tracker/?atid=384108&group_id=21935&func=browse