How To Convert a UserBase Manual to Docbook/ru: Difference between revisions
(Updating to match new version of source page) |
(Updating to match new version of source page) |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 11: | Line 11: | ||
* Check that the pages of your manual follow the [[Special:myLanguage/Tasks_and_Tools|author guidelines of UserBase]] and [[Special:myLanguage/Typographical_Guidelines|typographical guidelines]]. | * Check that the pages of your manual follow the [[Special:myLanguage/Tasks_and_Tools|author guidelines of UserBase]] and [[Special:myLanguage/Typographical_Guidelines|typographical guidelines]]. | ||
* Check if every page has its header according to the level of this page in table of contents. | * Check if every page has its header according to the level of this page in the table of contents. | ||
:{| | :{| | ||
| Line 111: | Line 111: | ||
{{Input|1=<nowiki><DPL> | {{Input|1=<nowiki><DPL> | ||
nottitlematch = %/__|%/zh-%|%(%) | nottitlematch = %/__|%/zh-%|%pt-%|%(%) | ||
titlematch = | titlematch = Appname/Manual% | ||
namespace = | namespace = | ||
columns = 1 | columns = 1 | ||
format = ,\n* [[%PAGE%|%TITLE%]],, | format = ,\n* [[%PAGE%|%TITLE%]],, | ||
| Line 119: | Line 119: | ||
<!--{{-->Replace '''''Amarok''''' with the name of your application, put it on your user page, and click on <menuchoice>Preview</menuchoice>. Rearrange the list according to the ToC of your manual. | <!--{{-->Replace '''''Amarok''''' with the name of your application, put it on your user page, and click on <menuchoice>Preview</menuchoice>. Rearrange the list according to the ToC of your manual. | ||
}} | |||
{{Note|1=If You are working with the Amarok manual be aware that it does not fully conform to manual page naming conventions. You can use | |||
{{Input|1= titlematch = Amarok/Manual%{{!}}Amarok/QuickStartGuide%}} | |||
(Note: No space characters in title pattern!) | |||
}} | }} | ||
| Line 184: | Line 189: | ||
* Create the following script file (named <tt>buildpdf.sh</tt>) in your DocBook directory: | * Create the following script file (named <tt>buildpdf.sh</tt>) in your DocBook directory: | ||
{{Input|1= | |||
<syntaxhighlight lang="bash">#!/bin/bash | <syntaxhighlight lang="bash">#!/bin/bash | ||
export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4. | export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.5/catalog:/usr/share/kf5/kdoctools/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.5/docbook | ||
# add -d to command below to keep the /tmp folder, so you can examine the generated tex. | # add -d to command below to keep the /tmp folder, so you can examine the generated tex. | ||
./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \ | ./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \ | ||
| Line 199: | Line 202: | ||
-I $KDEDIR/share/doc/HTML/en/ \ | -I $KDEDIR/share/doc/HTML/en/ \ | ||
-X \ | -X \ | ||
$1</syntaxhighlight>}} | $1</syntaxhighlight>}} | ||
* Download KDE styles: | * Download KDE styles: | ||
{{Input|1=<nowiki>git clone git://anongit.kde.org/websites/docs-kde-org.git</nowiki>}} | {{Input|1=<nowiki>git clone git://anongit.kde.org/websites/docs-kde-org.git</nowiki>}} | ||
Latest revision as of 17:10, 27 January 2019
Вступление
Так, текущая процедура довольно корявая, код скрипта не очень-то и красивый, скрипт недостаточно «умный» и др. Единственным оправданием может служить то, что этот способ однажды работает 
.
Если вы хотите усовершенствовать процедуру, имеете хорошие навыки программирования на языке Python, хорошо знакомы с принципами создания учебников в формате docbook, вы можете приложить собственные усилия к улучшению процесса. Пожалуйста, свяжитесь с пользователем Yurchor, если вы хотите помочь.
Preparing Pages for Conversion
- Check that the pages of your manual follow the author guidelines of UserBase and typographical guidelines.
- Check if every page has its header according to the level of this page in the table of contents.
Reference table UserBase Docbook Comment ==Section== <chapter> ===Section=== <sect1> ====Section==== <sect2> =====Section===== <sect3> ======Section====== <sect4> Avoid using this last level if possible
- Check if all table cells have space after the pipe character. This rule conforms with traditional wiki formatting.
- Make application name formatting consistent (avoid using Amaroks, do use Amarok's).
- Ensure that all images are in PNG format.
- Remove all non-printable characters from image names.
Export
- Prepare the page list (strip from UserBase addresses http://userbase.kde.org). Example for Amarok:
Amarok/Manual/Introduction Amarok/QuickStartGuide Amarok/QuickStartGuide/GettingStarted Amarok/QuickStartGuide/TheAmarokWindow Amarok/QuickStartGuide/TheMusicCollection Amarok/QuickStartGuide/Playlists Amarok/QuickStartGuide/TheContextView Amarok/QuickStartGuide/HowToDealWithProblems Amarok/QuickStartGuide/Glossary Amarok/Manual/AmarokWindow Amarok/Manual/AmarokWindow/Toolbar Amarok/Manual/AmarokWindow/MediaSources Amarok/Manual/AmarokWindow/ContextPane Amarok/Manual/AmarokWindow/PlaylistPane Amarok/Manual/ConfiguringAmarok Amarok/Manual/ConfiguringAmarok/ChangingLayout Amarok/Manual/Organization Amarok/Manual/Organization/Collection Amarok/Manual/Organization/CollectionScanning Amarok/Manual/Organization/Collection/SearchInCollection Amarok/Manual/Organization/Collection/OrganizeCollection Amarok/Manual/Organization/Collection/RemoteCollections Amarok/Manual/Organization/Collection/RemoteCollections/Ampache Amarok/Manual/Organization/Collection/RemoteCollections/DAAP Amarok/Manual/Organization/Collection/RemoteCollections/Samba Amarok/Manual/Organization/Collection/RemoteCollections/UPnP Amarok/Manual/Organization/Collection/ExternalDatabase Amarok/Manual/Organization/Collection/WorkingWithMediaDevices Amarok/Manual/Organization/CoverManager Amarok/Manual/Organization/TagEditor Amarok/Manual/Organization/Transcoding Amarok/Manual/Organization/ScriptManager Amarok/Manual/Playlist Amarok/Manual/Playlist/SavedPlaylists Amarok/Manual/Playlist/PlaylistFiltering Amarok/Manual/Playlist/QueueManager Amarok/Manual/Playlist/DynamicPlaylists Amarok/Manual/Playlist/AutomaticPlaylistGenerator Amarok/Manual/Various Amarok/Manual/Various/Moodbar Amarok/Manual/Various/AmarokOnOtherPlatforms Amarok/Manual/Various/AmarokOnOtherPlatforms/NonKDE Desktops Amarok/Manual/Various/AmarokOnOtherPlatforms/Windows Amarok/Manual/Various/AmarokOnOtherPlatforms/OSX Amarok/Manual/Various/TroubleshootingAndCommonProblems Amarok/Manual/Various/FAQ Amarok/Manual/References Amarok/Manual/References/MenuAndCommandReference Amarok/Manual/References/MenuAndCommandReference/AmarokMenu Amarok/Manual/References/MenuAndCommandReference/ViewMenu Amarok/Manual/References/MenuAndCommandReference/Playlist Amarok/Manual/References/MenuAndCommandReference/Tools Amarok/Manual/References/MenuAndCommandReference/Settings Amarok/Manual/References/MenuAndCommandReference/Help Amarok/Manual/References/KeybindingReference Amarok/Manual/References/KeybindingReference/GlobalShortcuts Amarok/Manual/References/KeybindingReference/AmarokShortcuts Amarok/Manual/References/Credits and License
Tip
You can obtain the full list of pages for your application with the following script:
<DPL> nottitlematch = %/__|%/zh-%|%pt-%|%(%) titlematch = Appname/Manual% namespace = columns = 1 format = ,\n* [[%PAGE%|%TITLE%]],, </DPL>Replace Amarok with the name of your application, put it on your user page, and click on . Rearrange the list according to the ToC of your manual.
Note
If You are working with the Amarok manual be aware that it does not fully conform to manual page naming conventions. You can use
titlematch = Amarok/Manual%|Amarok/QuickStartGuide%(Note: No space characters in title pattern!)
- Go to the export page.
- Paste the page list into the text field.
- Click on .
- Save the file. The saved file will be called Manual.xml in what follows.
Conversion
- Install Subversion package for your system.
- Checkout the latest version of conversion script:
svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/
- Copy Manual.xml to the script folder.
- Add a line containing
144.76.227.197 userbase.kde.org
to the file /etc/hosts . (You will need root privileges for this. You only need to do this once.)
- Run
python wiki2docbook.py Manual.xml
if you want to download all screenshots (it takes some time to download all images from UserBase, grep and wget should be installed), orpython wiki2docbook.py -s Manual.xml
if you need not to download images.
Post-processing
- Rename Manual.xml.docbook to index.docbook.
- Check if conversion was done correctly:
checkXML index.docbook
- Fix the errors (better on UserBase pages).
- Convert docbook to HTML:
meinproc4 index.docbook
- Check HTML pages (all images should be visible, links should not lead to 404-pages).
- Replace big images by thumbnails using convert from ImageMagick
- Fix links in docbook, so they lead to docbook section, not UserBase pages.
- Fix application name according to KDE entity list.
- Copy index.docbook and images to your /doc folder and commit them to repository.
Updating Your DocBook from UserBase
To update your converted docbook please use the following procedure:
- Re-export XML from UserBase. See Export section.
- Use the script to update the content (headers with abstract and keywords and footer will be kept):
python wiki2docbook.py -r index.docbook Manual.xml
- Check the docbook, rename the file into index.docbook and commit it with screenshots into your repository.
Converting DocBook into Other Format
Converting into PDF
Usually, there is no need to convert DocBook manually. You can download the converted PDFs from KDE Documentation site.
Should you need additional customization please do as follows:
- Make sure that you have some LaTeX distribution installed (usually, TeXLive).
- Create the following script file (named buildpdf.sh) in your DocBook directory:
#!/bin/bash export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.5/catalog:/usr/share/kf5/kdoctools/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.5/docbook # add -d to command below to keep the /tmp folder, so you can examine the generated tex. ./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \ kdestyle\ -o $(pwd | awk -F/ '{ print $NF }').pdf \ -P latex.output.revhistory=0 -P newtbl.use=1 \ -P imagedata.default.scale=pagebound \ -P literal.width.ignore=1 \ -I $KDEDIR/share/doc/HTML/en/ \ -X \ $1
- Download KDE styles:
git clone git://anongit.kde.org/websites/docs-kde-org.git
- Tweak dblatex-cvs-install/bin/dblatex in like this
#!/bin/sh TEXINPUTS=:/path/to/your/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS export TEXINPUTS /path/to/your/dblatex-cvs-install/share/dblatex/scripts/dblatex $*
(Change /path/to/your/ as appropriate)
- Copy KDE styles (/dblatex-cvs-install/share/dblatex/latex/contrib/) to some TeX dir where it can be found by LaTeX installation (I have copied them to /usr/share/texmf-dist/tex/latex/kde).
- Update paths with
mktexlsrfrom root.
- Run
./buildpdf.sh index.docbook. This should create ready-to-use PDF file for you. You can stop on this step if you do not want to tweak it.
- Copy all files from /tmp/tpb-your_user-digits to the work directory.
- Customize and edit tex file in Kile as appropriate.
- Compile PDF file with Alt + 6.
Converting into EPUB
- Make sure that Calibre is installed in your system.
- Convert your DocBook into HTML first. Use
meinproc4 index.docbookfor this.
- Start Calibre and choose .
- Select index.html in your DocBook folder. Wait until the book is loaded.
- Choose .
- Fill the metadata fields as appropriate.
- Press and wait until the work is done.
- Copy the book from ~/Calibre Library on your ebook reader.