{"id":26493695,"url":"https://github.com/redhat-openstack/openstack-manuals-convert","last_synced_at":"2025-06-28T01:02:13.589Z","repository":{"id":143947094,"uuid":"9772180","full_name":"redhat-openstack/openstack-manuals-convert","owner":"redhat-openstack","description":null,"archived":false,"fork":false,"pushed_at":"2013-10-04T13:29:53.000Z","size":484,"stargazers_count":1,"open_issues_count":9,"forks_count":1,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-20T09:56:40.164Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"XSLT","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redhat-openstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-30T13:58:23.000Z","updated_at":"2014-09-23T10:51:47.000Z","dependencies_parsed_at":"2023-03-21T11:00:48.333Z","dependency_job_id":null,"html_url":"https://github.com/redhat-openstack/openstack-manuals-convert","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/redhat-openstack/openstack-manuals-convert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-openstack%2Fopenstack-manuals-convert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-openstack%2Fopenstack-manuals-convert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-openstack%2Fopenstack-manuals-convert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-openstack%2Fopenstack-manuals-convert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redhat-openstack","download_url":"https://codeload.github.com/redhat-openstack/openstack-manuals-convert/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-openstack%2Fopenstack-manuals-convert/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260654643,"owners_count":23042676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-20T09:56:44.738Z","updated_at":"2025-06-19T00:06:53.155Z","avatar_url":"https://github.com/redhat-openstack.png","language":"XSLT","readme":"# openstack-manuals-convert\n\n## Introduction\n\nThe Publican DocBook XML publishing tool applies relatively strict standards to the content and structure of input XML files. As such it has difficulty building documentation projects which have not been written from the ground up with Publican in mind, at least without some initial alteration.\n\n**openstack-manuals-convert** is a script for taking DocBook XML from one such project and converting or rebasing it such that it can be built using Publican. The project in question is **openstack-manuals** which contains the XML for the documentation which appears on the http://docs.openstack.org site. The source XML is available here:\n\n    https://github.com/openstack/openstack-manuals\n\nAs **openstack-manuals-convert** is designed primarily for use with the guides contained in the **openstack-manuals** project it will not necessarily convert any and all guides to a format that is usable by Publican. **Publicanize** is however provided as a reference for some of the common issues you will face in performing such a conversion and possible solutions.\n\n## Prerequisites\n\n* Bash.\n* Publican 3.2.1+.\n* Saxon XSLT 2.0 processor.\n* ~/.publican.cfg file containing firstname, surname, and email information, This\n  is used to generate a revision history entry.\n\n    firstname: Shadow\n    surname: Man\n    email: shadowman@example.com\n\n## Building\n\nTo build **openstack-manuals-convert**:\n\n    $ git clone https://github.com/redhat-openstack/openstack-manuals-convert.git\n    $ cd ./openstack-manuals-convert\n    $ ./autogen.sh\n    $ make rpms\n\n## Installing\n\nUse **yum** to **install** or **reinstall** the built package.\n\n## Running\n\nTo run **openstack-manuals-convert**:\n\n    $ git clone https://github.com/openstack/openstack-manuals.git\n    $ cd openstack-manuals/**GUIDE**\n    $ openstack-manuals-convert **[OPTIONS]**\n\nBy default the Publican-friendly version of the guide will be output to **./target/publican/**.\n\n## Options\n\nUsage:\n\n    openstack-manuals-convert [OPTIONS]\n\n````\nAvailable OPTIONS:\n\n  [--abstract=ABSTRACT]            Override the abstract used in the book.\n  [--blacklist=BLACKLIST]          Blacklist XML files that match the list of\n                                   files in the BLACKLIST file. The file is of\n                                   the format:\n                                   \u003cblacklist\u003e\n                                     \u003centry file='FILE.xml' /\u003e\n                                   \u003c/blacklist\u003e\n                                   Inclusion of files matching the provided\n                                   name, regardless of path, will be removed.\n                                   Images may be blacklisted in the same way.\n  [--brand=BRAND]                  Override publican brand, default is \\\"common\\\".\n  [--config=CONFIG]                Provide a path to an alternative publican.cfg\n                                   template.\n  [--customxsl=CUSTOMXSL]          Provide a path to a custom XSL transformation\n                                   to apply to each XML file processed.\n  [--docname=DOCNAME]              Set a document name to be used in the\n                                   publican.cfg file. This will be used when\n                                   naming the package instead of the guide\n                                   title.\n  [--help]                         Display usage information.\n  [--images=IMAGEDIR]              Override the images used in the book with\n                                   those in IMAGEDIR. Directory structure and\n                                   image file names must match.\n  [--output=OUTPUT]                Provide a path to use for generated output.\n  [--productname=PRODUCTNAME]      Override the product name used in the book.\n  [--productnumber=PRODUCTNUMBER]  Override the product number used in the book.\n  [--profile=PROFILE]              Set profiling directives, e.g.:\n                                   \"condition: user,os: rhel\"\n  [--revision=REVISION]            Override the revision of the book,\n                                   default is of the form:\n\n                                       PRODUCTNUMBER-YYYYMMDD.\n\n  [--subtitle=SUBTITLE]            Override the subtitle of the book.\n  [--title=TITLE]                  Override the title of the book.\n  [--web_version_label=LABEL]      Override the web_version_label directive,\n                                   the default is the name of the git branch\n                                   the content is being transformed from.\n````\n\nExample:\n\n````\n$ openstack-manuals-convert --brand=\"publican-fedora\" \\\n                            --productname=\"Fedora\" \\\n                            --productnumber=\"20\"\n                            --title=\"OpenStack User Guide\"\n````\n\n### Publican RFEs\n\nThese Publican RFEs have been raised, implementation of them will streamline the conversion and packaging process:\n\n* [893199](https://bugzilla.redhat.com/893199) Add CSS to common-db5 for centering \"author\" tag (same styling as corpauthor in DocBook 4.5)\n* [953675](https://bugzilla.redhat.com/953675) XSL for abstract and subtitle detection assumes info element is root node of XML file (not always the case when using info file directive).\n* [1004955](https://bugzilla.redhat.com/1004955) Publican print unused incorrectly detects files from higher levels in the directory structure (but within the book) as unused.\n\nThe issue with abstract detection ([953675](https://bugzilla.redhat.com/953675)) prevents the use of Publican's package action. To work around this issue it is necessary to apply **abstract.xsl.patch** to **/usr/share/publican/xsl/abstract.xsl** like so:\n\n````\n$ sudo patch -p0 /usr/share/publican/xsl/abstract.xsl \u003c abstract.xsl.patch\n$ sudo patch -p0 /usr/share/publican/xsl/subtitle.xsl \u003c subtitle.xsl.patch\n````\n\nIt is anticipated that this action will no longer be required in future releases of Publican (4+).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-openstack%2Fopenstack-manuals-convert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredhat-openstack%2Fopenstack-manuals-convert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-openstack%2Fopenstack-manuals-convert/lists"}