Extension:DocBookExport/ru
DocBookExport Статус релиза: стабильно |
|
---|---|
Реализация | Функция парсера |
Описание | Lets you create DocBook from pages |
Автор(ы) | Nischay Nahata (Nischayn22обсуждение) |
Последняя версия | 1.0 |
MediaWiki | 1.25 |
PHP | 5.5+ |
Лицензия | MIT License |
Скачать | README |
|
|
Ежеквартальные загрузки | 16 (Ranked 110th) |
Переведите расширение DocBookExport, если оно доступно на translatewiki.net | |
Проблемы | Открытые задачи · Сообщить об ошибке |
The DocBookExport extension lets you create a DocBook from selected wiki pages. You can download the DocBook as an XML file. Other formats supported are ODT, HTML and PDF.
Установка
- Скачайте и распакуйте файл(ы) в папку с названием
DocBookExport
в вашей папкеextensions/
.
Вместо этого разработчикам и соавторам кода следует установить расширение из Git, используя:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/DocBookExport - Добавьте следующий код в конце вашего файла LocalSettings.php :
wfLoadExtension( 'DocBookExport' );
- Configure as required
- Готово – Перейдите на страницу Special:Version на своей вики, чтобы удостовериться в том, что расширение успешно установлено.
Настройка
$wgDocbookExportPandocServerPath
- The URL for the html_to_docbook script on its server, e.g. http://example.com/html_to_docbook
$wgDocbookDownloadServerPath
- The URL for the directory in which generated files will be placed.
$wgDocBookExportImportXSLRepoPathPDF
- The path to a git repo for pulling the XSL files from.
$wgDocBookExportXSLRepository
- The path of the XSL file to be used for DocBook generation.
Dependencies
On the wiki, install the Figures extension, which supports defining figures in MediaWiki.
On either the wiki's server, or any other server, install the following:
- html_to_docbook, as per directions in the README file.
- pandoc: see
https://github.com/jgm/pandoc/releases
for the latest version. Then, to install on Ubuntu, use the following commands, replacing the version number as per the latest release:
sudo wget github.com/jgm/pandoc/releases/download/2.16.2/pandoc-2.16.2-1-amd64.deb
sudo dpkg -i pandoc-2.16.2-1-amd64.deb
For HTML output
To download the output as an HTML file, install the following, on the same server that holds html_to_docbook:
- xlstproc: for Ubunutu, install using:
sudo apt install xsltproc
For PDF output
To download the output in PDF format, install the following software, on the same server that holds html_to_docbook:
- saxon: see http://www.sagehill.net/docbookxsl/InstallingAProcessor.html
- Note that you need to also have the Docbook Saxon extension installed. See: http://www.sagehill.net/docbookxsl/InstallingAProcessor.html#InstallSaxon
- FOP: for Ubuntu, install using:
sudo apt-get install fop
For Zip output
To download DocBook files in Zip format, install the following, on the same server that holds html_to_docbook:
- ZipArchive PHP extension: if it's not already within your PHP installation, you can install it in Ubuntu using:
sudo apt-get install php7.0-zip
service apache2 restart
Usage
To create a book, first define the page structure using the #docbook parser function. Here is an example call:
{{#docbook: page structure= ? Bowling Introduction + Intro Chapters * How I buy shoes(orientation=landscape) * Testing page ** Buying clothes intro,Buying shoes(title=Buying the right clothes,header=section header,header_left=section left header) ? Appendix |title=My Guide to Bowling |productname=MY PRODUCT NAME(class=trade) |corpauthor=Wikiworks |biblioid=MY Bibliod(class=pubnumber) |volumenum=1 |revhistory=13.1,24 June 2020 |keywordset=KEYWORD1,KEYWORD2 |subjectset=DO NOT REMOVE |subtitle=Edition M Version 1 |cover page=Cover Contents |header=My Guide to Bowling |footer=My Guide to Bowling |header_left=My Guide to Bowling Left |footer_left=My Guide to Bowling Left |header_right=My Guide to Bowling Right |footer_right=My Guide to Bowling Right |index=1 |index term categories=index terms(group by=Index has Group) |index terms=shoe,clothes |orientation=portrait |section_autolabel_max_depth=6 |external_link_color=green |size=A4 |columns=1 |timestamp=1 |watermark.text=DRAFT |watermark.rotation=-45 deg |watermark.color=#f2f2f2 |watermark.font.family=Sans |watermark.font.size=12pt |title.font.family=Helvetica |body.font.family=Times Roman |body.font.size=12pt |footnote.font.family=Times Roman |footnote.font.size=8pt |margin-inner=0.5in |margin-outer=0.5in |margin-top=0.5in |margin-bottom=0.5in |xsl_import_path=/var/www/html/mycustomxsl }}
On saving the page, a link will be generated which directs you to a special page Special:GetDocbook. The request is then pushed to the server handling HTML-to-DocBook generation. Once the DocBook is generated, links will be made available on the Special page to download the DocBook: in XML, HTML, ODT and PDF formats.
The parameters shown can be customized as follows:
page structure
is used to define the wiki pages that will be part of the DocBook as cover, sections and chapters. The first line starts with a'?'
and indicates the preface,+
indicates a page which contains multiple chapters, each chapter is specified using a h1 heading.*
indicates a chapter and**
indicates a section of that chapter. Sub-sections can be defined using***
or****
and so on. The last line again starts with a'?'
and indicates the wiki page to be used as the appendix. Sometimes you may want to merge contents of multiple wiki pages to one section/chapter. For that you can add a comma separated list of such pages as well. You can also customize the title of such a section by adding the following wikitext(title=)
at the end of the line. Similarly you can customize the header/footer/header left and right/footer left and right for a specific section by using the(header=)
syntax at the end of the line as shown in the example. To change the orientation of a specific chapter or section add(orientation=landscape)
title
This parameter defines the name of the DocBook. This doesn't relate to any wiki page and is only used to name the files and the title of the docbook.cover page
This parameter specifies the wiki page to be used as the cover page.header
This parameter specifies the header to be used for every page of the docbook.footer
This parameter specifies the footer to be used for every page of the docbook.header_left
This parameter specifies the header on the left side of the page to be used for every page of the docbook.footer_left
This parameter specifies the footer on the left side of the page to be used for every page of the docbook.header_right
This parameter specifies the header on the right side of the page to be used for every page of the docbook.footer_right
This parameter specifies the footer on the right side of the page to be used for every page of the docbook.index
This parameter should be set to 1 in order to generate the index.index terms
This parameter is a comma separated list of terms that should be indexed.index term categories
If you have wiki pages for all your index terms you can add them to a category and mention it here.orientation
Lets you customize the orientation of the output format.section_autolabel_max_depth
Lets you set the parameter section.autolabel.max.depth in Docbook.external_link_color
Lets you set the color for external links for PDF.size
Lets you customize the size of the page.column
Lets you customize the number of columns.margin-*
Lets you customize the margin for each side of the page.timestamp=1
Adds a timestamp on the bottom-right part of the cover page with the following text: Produced from <wiki URL> on <timestamp>.title.font.family=Helvetica
Lets you customize the font for the title of the PDF.body.font.family=Times Roman
Lets you customize the font for the body of the PDF.body.font.size=12pt
Lets you customize the font size for the body of the PDF. The font size for the footnotes would be 0.8 times this size.footnote.font.family=Times Roman
Lets you customize the font family for footnote.footnote.font.size=8pt
Lets you customize the font size for the footnote of the PDF.watermark.text=DRAFT
Lets you add a watermark in the PDF. Watermark is a text used as a SVG image with additional options for styling the text.watermark.font.size=8px
Lets you customize the font size on the watermark in the PDF.watermark.font.family=Sans
Lets you customize the font on the watermark in the PDF.watermark.rotation=-45 deg
Lets you rotate the text on the watermark in the PDF.watermark.color=#f2f2f2
Lets you customize the font color on the watermark in the PDF.xsl_import̜_path=/var/www/html/mycustomxsl
Lets you provide your custom XSL configuration files. This path would be replaced in the "DOCBOOKXSLPLACEHOLDER" path in the xsl template file instead of the standard docbook xsl files.- All other parameters are self-explanatory DocBook element tags.
DocBook supports figures which are images or other media that can be referenced elsewhere in the document. A separate list of figures is also prepared. To define a figure you need to use the Figures extension.
Grouping of indexes is possible as well. To use this feature add the following wikitext to the index term page (create if required) specifying the group name:
{{#docbook_index:grouping=Group_name}}
Another approach to add grouping is by specifying a Semantic MediaWiki property which contains the group name, this can only be done for index term categories and can be specified using "group by" parameter as follows:
|index term categories=index terms(group by=Index has Group)
While styling in wiki pages is easy using CSS, the same styling is not carried forward to the DocBook. This can be a problem with tables which sometimes should have different widths for different columns. To solve this you can specify a class with the following format: colwidth-80-20, the extension will then convert it to the following DocBook XML which ensures that the column width is maintained in the DocBook:
<colspec colwidth="80*" align="left"/> <colspec colwidth="20*" align="left"/>
Similarly, for a three-column table specify the class as "colwidth-80-10-10".
Credits
This extension has been written by WikiWorks.
Process diagram
The following diagram shows how the various software and utilities are used together to create the different output formats that DocBookExport supports, and hopefully makes it easier to understand which dependencies are needed for which outputs. Note that docbook2odf comes pre-bundled with the html_to_docbook library; the rest would need to be installed individually, if they are not already on your system.
Development and help
You are welcome to submit bug fixes in Gerrit and bug reports and feature requests in Wikimedia Phabricator under phab:tag/mediawiki-extensions-docbookexport.
Please also feel free to contact the author or WikiWorks for consulting on further developments, feature requests or bug fixes on this extension.
See also
- PDF export - summary of all PDF export extensions