tomschr / dbcookbook Goto Github PK

Problem

Maybe it's worth to think about creating a specific GitHub domain dedicated to this project.

Related to #19

Solution

With a domain, it could be easier to separate tools, result HTML, and source code.

• redirect pages from SourceForge to GitHub
• fix all old links
• separate build mechanics from source code

Moved from https://sourceforge.net/p/doccookbook/tickets/21/

These are some of the ideas about manipulating the DocBook document structure. The list is no guarantee that all will be implemented.

• (Combining two DocBook documents with XSLT)
• Modularizing DocBook Documents with Assemblies
• Creating a RevHistory from RSS and Atom
• Resolving XInclude Elements
• Autogenerate indexterm ranges
• Renaming Image Filenames
• Checking Style Guide Issues with XSLT
• Using other Placeholders (PIs, XIncludes, phrase...)
• Using Entities as Placeholders
• Preserving Entities #43

Moved from https://sourceforge.net/p/doccookbook/tickets/18/

There is a chapter missing about EPUB customizations

Moved from https://sourceforge.net/p/doccookbook/tickets/22/

These are some of the ideas about print customizations. The list is no guarantee that all will be implemented.

• Restarting page number on each chapter
• Designing Title Pages
• Designing Pages for Novels
• Designing Pages for Lexicons, Referene Book and Catalogs
• Designing Pages for Magazines and News Papers
• Designing Pages for Technical Books
• Adapting Chapter and Sections Titles
• Make Font Sizes Consistent / Standardizing Font Sizes (Le Corbusier)
• Index
• Designing TOCs
• Colorizing Table Rows
• Adding Graphics in Title Page
• Adding Logos in Header or Footer
• Adding Current Time and Date Information
• Separating Chapter Number from Title
• Footnotes
• Marginalia
• Endnotes
• Adorning Paragraphs with Initials (Openings)
• Formatting Titles
• Numbering Titles
• Choosing Open Source Fonts
• Adding Change Bars
• Initials/Drop Caps
• Influence Leading in Flow Text (=line-height in paras)
• Hyphenating in Verbatim Environments (long lines in screen, programlisting)
• Showing Cropmarks
  http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/examples/fo/advanced/bleed-and-crop-marks.fo?view=markup&pathrev=800143
• Barcode
• Add Typographical Superiors and Inferiors
• Adding Fonts to FO Formatter
• Creating Page Definitions with Inkscape
• Styling Labels Differently than Titles (Separating Labels and Titles)
• Using Text Figures http://en.wikipedia.org/wiki/Text_figures
• Using MathML in Formulas
• Influencing the TOC Bookmark Levels in PDF
• Finding the correct Font Name
• Hyphenating URLs

Problem

The project and book name is a bit cheasy.

Solution

Rename it to "DocBook Style Guide: Best Practices for Authors and Developers"

Checklist

• move project to the new domain
• adapt URLs in the document itself
• adapt URL(s) in/for Travis
• correct README
• something else...?

Problem

Although DocBook does not enforce how you create your project, it could be helpful to give some information about the "things around DocBook".

Solution

Some ideas that could be integrated under this topic. The list is no guarantee that all will be implemented:

• Creating a Structure for your DocBook Projects
• Using the xmllint Shell to test XPath expressions
• Managing your XML Catalogs
• Managing your Workflow Tools
• Using XML Parsers
• Using a XSLT Processors
• Using an XProc Processor
• Choosing a XML Editor
• Configuring FOP

Related issue: #11

Is your feature request related to a problem? Please describe.
Describe the <?dbhtml?> processing instruction for chunking.

Additional context
HTML, related to #10

Moved from https://sourceforge.net/p/doccookbook/tickets/19/

These are some of the ideas about markup. Most is probably already mentioned in "The Definitive Guide" so not all can/will be implemented.

• Knowing the Differences Between DocBook's Version 4 and Version 5

• Modularize your Document with Assemblies

• Differentiate DocBook Elements (Divisions, Block, Inline)

• Writing Topics with DocBook

• Using Tables

• Writing a Glossary

• Writing a Reference

• Writing Bibliographies

• Inserting Indexterms

• Adding Images

• Adding Codelistings

• Utilize Extended XLinks
  http://www.balisage.net/Proceedings/vol7/html/Vlist01/BalisageVol7-Vlist01.html

• Knowing DocBook Derivates: Simple DocBook, Publishers Schema

• Using Manpage Notation

  <citerefentry>
    <refentrytitle>foo</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>
  

• Knowing the Difference of Crossreferences and Links

• Using Lists

• Distinguish Between Section and SectX

• Implementing Cross References

• Inserting Remarks

• Choosing Between Two Link Methods

• Adding Multiple Indices

• Inserting Inline Quotes

• Modularize your Document with XIncludes

Is your feature request related to a problem? Please describe.
How to use and preserve entities are not described.

Describe the solution you'd like
Add topics about how to use and how to preserve entities

Additional context
Should be added to "Manipulating DocBook Document Structure" chapter.

Related to #8

Problem

You are using the URL "http://docbook.sourceforge.net/release/xsl-ns/current/fo/docbook.xsl" in various programlistings. For example in the "Print Customization" chapter: "http://doccookbook.sourceforge.net/html/en/dbc.fo.design-titlepages.html"

Expected Behaviour

As far as I know this is an old URL to version 1.78.x. From my opinion this should be "https://cdn.docbook.org/release/xsl/current/fo/docbook.xsl", which is 1.79.2 or newer.

Is your feature request related to a problem? Please describe.
Describe the HTML parameters for chunking

Additional context
HTML, related to #10

Feature Description

A book should contain a topic concerning configuring and using fonts with FO-formatter. This topic will be Apache FOP related only.

Expected Wishlist

1. How to configuring fonts (in general).
2. What is autodetect and how it influence a look of the document.
3. How someone should deal with the ##### signs instead of characters while rendering PDF file from DocBook document containing non-Latin character.

Relations

Not know yet.

Problem

User would like to leave a comment for a specific page.

Possible Solutions

• Create infrastructure to enable users to insert comments for each paragraphs, similar to the Mercurial book (see http://hgbook.red-bean.com/)

• Another idea: Probably a link to the GH issue page should be enough.

• Use https://commento.io/

Problem

The code pretty printer from Google has changed its link:

Old link: http://code.google.com/p/google-code-prettify/
New link: https://github.com/google/code-prettify

http://doccookbook.sourceforge.net/html/en/dbc.html.sh.google-code-prettifiy.html

Reported by Peter Schmelzer

Expected Behaviour

Change link to new link.

Moved from https://sourceforge.net/p/doccookbook/tickets/23/

These are some of the ideas about (X)HTML customizations. The list is no guarantee that all will be implemented.

• Attaching CSS (to your HTML) (explain different methods)
• Alt Text for Images
• Creating Callouts
• Syntax Highlighting
• Implementing Clickable TOCs
• Deciding where to put Customizations (CSS or XSLT)
• Integrating Google's Web Fonts
• Combining DocBook and Web Frameworks (Twitter Bootstrap, Bulma, Foundation, etc)
• Separating Label and Title in Headings
• Customize chunking process
• Document dbhtml PI
• Control chunking
• Adding Permalinks
• Creating Breadcrumbs (simple, sophisticated)

Is your feature request related to a problem? Please describe.

The current look of my HTML pages are a bit... boring. Furthermore, it should be readable on smartphones and desktop PCs.

• improve CSS
• take into account smartphones
• use grid(s) to describe the layout
• use alternative stylesheets?

Describe the solution you'd like

• https://gridbyexample.com/examples/
• https://developer.mozilla.org/en-US/docs/Web/CSS/Alternative_style_sheets

Is your feature request related to a problem? Please describe.
Missing sitemap.xml to improve Google SEO results.

Describe the solution you'd like
Add a sitemap.xml.

Additional context

• To split big sitemaps into smaller ones, use this URL: https://support.google.com/webmasters/answer/75712?visit_id=0-636655319635101674-843455639&rd=1

• Sitemap Schema: https://www.sitemaps.org/schemas/sitemap/0.9/

Chapter 1, section 1.2 Selecting the Right Top Level Element, Discussion section

There a many more possible root elements, not only book.

It looks like a grammar error.
I think that it should be written as "There are many more possible root elements, not only book.
"

Moved from https://sourceforge.net/p/doccookbook/tickets/17/
Reported by David Cramer.

Certain programlistings contain very long lines:

http://doccookbook.sf.net/html/en/DoCookBook.html#dbc.structure.remove-blocks-in-para

As a result, the entire html page has a huge horizontal scroll bar. Perhaps put a box with a scroll bar (if necessary) around each programlisting?

Moved from https://sourceforge.net/p/doccookbook/tickets/16/
Reported by Michael Wiedmann

Please create an EPUB version of the source files.
A first try using the ruby script dbtoepub (which is part of the DocBook-XSL distribution) without any customization already gives very promising output!

Make HTML and PDF also available as downloads.

Problem

Currently, all HTML pages are stored at SourceForge. It would be nice to have it all under one roof.

Expected Behaviour

• All HTML pages can be accessed from tomschr.github.io/dbcookbook.
• redirect pages from SourceForge to GitHub

See Also

• https://docs.travis-ci.com/user/deployment/pages/
• related issue #25

Problem

As a showcase, use assemblies in the future

Expected behaviour

• The main file is an assembly file
• The tool chain is adapted to produce the result from the assembly file

Moved from https://sourceforge.net/p/doccookbook/tickets/29/

Implement syntax highlighting in online output for screen or programlisting.

Useful links:

• http://alexgorbatchev.com/SyntaxHighlighter/
• http://softwaremaniacs.org/soft/highlight/en/
• http://code.google.com/p/google-code-prettify/

Reported from @sknorr via mail (found in http://doccookbook.sf.net/html/en/dbc.structure.move-blocks-in-para.html):

Example:

<para>
     This manual uses the following
     <!-- comment --><phrase>commands</phrase>:
     <screen>foo</screen>
</para>

Output is:

<para>
     This manual uses the following
</para>
<screen>foo</screen>

Patch:

diff --git i/en/xml/structure/remove-blocks-in-para/move-blocks-outof-para.xsl w/en/xml/structure/remove-blocks-in-para/move-blocks-outof-para.xsl
index 5f87f64..5ed971e 100644
--- i/en/xml/structure/remove-blocks-in-para/move-blocks-outof-para.xsl
+++ w/en/xml/structure/remove-blocks-in-para/move-blocks-outof-para.xsl
@@ -33,7 +33,7 @@
       select="following-sibling::*[&dbselfblocks;][1]"/>
   </xsl:template>
 
-  <xsl:template match="d:para/*|d:para/text()" mode="copy">
+  <xsl:template match="d:para/node()" mode="copy">

Moved from https://sourceforge.net/p/doccookbook/tickets/26/

Write a colophon explaining how this book is/was produced; which tools, fonts, etc. are used

Problem

We need an issue template.

Expected Behaviour

Whenever someone opens a new issue, the user should see a basic structure.

See Also

• https://help.github.com/articles/creating-an-issue-template-for-your-repository/

Problem

The "Release" link in GitHub misses a HTML (or PDF) file which is automatically created by Travis CI.

Expected Behaviour

After a new release, Travis builds the HTML (or PDF) and uploads it to the "Release" page.

See also

• https://docs.travis-ci.com/user/deployment/releases/

Moved from https://sourceforge.net/p/doccookbook/tickets/25/

It seems, there is an interested in a chapter about [a] DocBook toolchain(s). The chapter could explain what software/tools you need, how to install it, and how to use it.

Unfortunately, this is a (very?) broad topic. Requirements, operating systems, and steps differ a lot. As such, DocBook does not have an "official" toolchain.

Currently, it's not of high priority for me, although it would be probably very beneficial. If someone wants to take this over, please go ahead! :-)

Moved from https://sourceforge.net/p/doccookbook/tickets/20/

These are some of the ideas about common customizations. The list is no guarantee that all will be implemented.

• Getting to Know Available DocBook XSL Stylesheets
• Getting an Overview -> maybe before any of the topics?
• Taking Advantage of Common Bibliography
• Taking Advantage of Common Glossary
• Colorising Profiled Text
  http://lists.oasis-open.org/archives/docbook-apps/201108/msg00100.html
• Creating Unit Test with XSpec
• Inserting Missing Glyphs in a Font
• Sharing text (entities)
• Extracting Information from Processing Instructions
• Getting Documentation Title
• Designing Title Pages
• Extending Language Files with your Own Text
• DocBook customization (through parameters or customization layers)
• Outputing Time and Dates
• Printing XPath from Stylesheet

Problem

The book needs a decent index, maybe created semi-automatically.

Solution

The book contains an index with the following properties:

• primary indexterm about (stylesheet) parameters
• primary indexterm about commands
• primary indexterm about options
• primary indexterm about DocBook elements

I would like to contribute to your cookbook as well as helping you to get it published. I have a relationship with Apress Books and I could have the manuscript submitted for publication. I am interested in anything I can contribute including existing and new content. I have a special interest in using open source tools to transform DocBook into content like pdf, html, and other open formats.

Currently I am finishing my second book with Apress and I will be available shortly to work on content for your book. I only ask to be considered a co-author should my contributions be considered good enough.

I look forward to hearing from you and providing new content for your book.

Thank you,
W. David Ashley
[email protected]
512.289.7506
Austin, Texas

Idea

How to use database driven reusable content in a Docbook article/book?

Expected Behaviour

• Show how to use Xquery to add database content to an Docbook article or book
• Maybe how to store Docbook contents in an XML database