RE: [docbook-apps] Tools to make DocBook easier

[Gerard Nicol]

Would anybody be interested in building a docbook VM environment with:

1. Docbook
2. Git
3. Build for man pages, PDF, HTML output etc.

I have experience setting thise things up, but need help with the docbook
customizations to make it all look nice.

My thinking is that there seems to be agreement that the default docbook
output looks pretty ordinary. My position is that people should be able to
download a VM image to produce good looking output out of the box, then if
they want, they can make changes to something that looks good, rather than
something that looks ordinary.

Any interest? If there is I'd be happy to share my skills in return for
working with others who can show me some things.

Gerard

-Original Message-
From: Eduard Tibet [mailto:eduard.ti...@gmail.com]
Sent: Thursday, September 17, 2015 8:53 AM
To: Kallauch, Benjamin (EEIN) 
Cc: docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] Tools to make DocBook easier

Benjamin,

as for CMS...

I (with help of my java-minded colleagues) setup custom build of Apache
Cocoon 2.2 as a XML Publishing Framework some years ago. This build is live
now within company and is used for internal company documentation.

It deals quite good with:
- Docbook files (we used v. 4.5).
- Conditional profiling (2-passes).
- pdf generation with FOP
- dynamically generation of documentation web site, including actual docs
version, trunk, etc.
- adaptive content, based on device.
- some more stuff...

However, some things are out of scope of Cocoon and are made at preprocess
level (shell scripts):
- SVN updates/checkouts (svn used for storing xml and images).
java-based svn-kit is much slower, than grab xmls from disk.
- XIncludes;
- building targetdb;
- some custom optimization for olinks [1]

I want personally to thank Bob for his insight on using Cocoon as an
automation technology in his book "DocBook XSL: The Complete Guide, Fourth
Edition", I read in the beginning of 2008.

[1] https://lists.oasis-open.org/archives/docbook-apps/201011/msg00073.html

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

RE: [docbook-apps] dblatex (was Re: [docbook-apps] Show off what you've done with Docbook)

[Gerard Nicol]

Is there a recent document that lists all of the alternative tools along
with their features and benefits?


-Original Message-
From: Warren Block [mailto:wbl...@wonkity.com] 
Sent: Wednesday, September 16, 2015 9:03 AM
To: maxwell 
Cc: docbook-apps@lists.oasis-open.org
Subject: [docbook-apps] dblatex (was Re: [docbook-apps] Show off what you've
done with Docbook)

On Sun, 13 Sep 2015, maxwell wrote:

> On 9/13/2015 2:45 PM, Warren Block wrote:
>> The FreeBSD DocBook toolchain almost supports dblatex, but the older 
>> versions did not have all the features we needed for PDFs.  Table of 
>> contents and some other things, as I recall.  We now have a port of 
>> the latest version of dblatex, but it dies mysteriously and needs 
>> more investigation.
>
> I don't recall exactly how we do the table of contents, but as I 
> recall it's literally a one liner.  For our grammars, we additionally 
> have a Table of tables, table of figures, and for one document a Table 
> of equations.  Also a glossary, bibliography (for which we use bibtex 
> data files, together with the Biber program, which has advantages over 
> the older bibtex program), and an index.  The glossary and index 
> require the appropriate XML elements, and of course the biblio requires
the .bib files, but otherwise it's all automagic.

Right.  We had been using an older version of dblatex, which was missing
some of those features.

> Most of the customization we've had to do has been on the LaTeX side, 
> for which we have two style sheets--one for producing PDFs for use 
> on-line, the other for camera-ready copy for the print publisher.
>
> Does your system die during the dblatex phase, or the LaTeX phase?  We 
> hardly ever see a failure in the dblatex phase, unless there's 
> actually an error in the DocBook XML.


-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

RE: [docbook-apps] Show off what you've done with Docbook

[Gerard Nicol]

Katie,

 

I started my IT career working with IBM mainframes. 

 

Mainframers live in a parallel upside down universe where simplicity is 
complexity and the more you need to know about something the more worthy it is 
of your admiration.

 

When I first started selling software I learned the hard way that most people 
“IT professionals” don’t know how to open a command prompt. So if it isn’t as 
easy as their iPhone to use you don’t make a sale.

 

To make matters worse, most people are incapable of understanding a manual, 
even if you have one and it is well written. So in the end, as a software 
vendor you need to have:

 

1.   Support people to do the work for the 70% of people who can’t do it 
for themselves even with a manual.

2.   YouTube videos for the 15% of people who would rather watch a How-To 
video than read a manual.

3.   A manual in web, PDF and hardcopy for those who insist on having a 
manual (who are the other 15% + some of the people above).

 

Other people might be seeing different things, but this is my experience.

 

The end result is that written manuals are only there for about 1 in 7 of my 
customers, and completely irrelevent to the others.

 

Do they teach people doing IT/Technology at University how to write 
documentation (or did they ever)?

 

If they do teach them, what platforms are they taught about?

 

Gerard

 

From: Katie Welles [mailto:ka...@inkwelle.com] 
Sent: Sunday, September 13, 2015 10:12 AM
To: docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] Show off what you've done with Docbook

 

Gerard's points 1 and 2 are quite valid.


Setting up my DocBook toolchain was quite the graduate course in frustration. I 
wrote up notes about how I set it up here: 
http://www.millermattson.com/blog/docbook-toolchain/, mostly so I could do it 
again years later after forgetting! 

 

And my client wanted quite a few customizations, so I had to delve very deeply 
into the XSLT which is an intricate tapestry of spaghetti. I ended up with a 
pretty intense customization chain, but even then, there were some nits I was 
never quite able to figure out. If I can find those notes I’ll post those on my 
blog, too.


I still say that the power of DocBook is not in its ability to create 
documents, but in its ability to output a document **and** HTML from the same 
source. But when 
i worked with it, we only generated HTML. And for all the monumental hassle of 
dealing with the toolchain + tortuously laboring in the XSLT, to just get a 
simple HTML site at the end was sad: I could have created something so much 
nicer in just straight HTML +CSS!

 

I've seen some pretty nice documents in this thread, but not so many 
HTML-plus-PDF pairs of documents (although I have yet to sit down and look at 
all the responses to this thread yet).  I think a nice looking document is fine 
— but it is a nice-looking document **paired with** navigable HTML is the real 
win.

The HSA Foundation specs, PDF and HTML, were output from a single data source.  
http://www.hsafoundation.com/html/HSA_Library.htm   We used Madcap Flare for 
this project, which is a fantastic tool with a price tag and learning curve 
which IMHO removes it from consideration outside of the corporate setting. So 
I’m still looking… and I’m not sure DocBook will cure this ill...

K.

RE: [docbook-apps] Show off what you've done with Docbook

[Gerard Nicol]

Tom,

I've been giving this some thought, and what had become evident to me is that I 
have no problem at all with the Docbook language.

After all, you can either learn to code it by hand, or use an editor like 
Oxygen. Either way, you do need to know the possibilities of the language, to 
know the best way to mark-up your document, but that's not really a problem.

There are 2 problems that I suspect for many make the difference between using 
the product and not:

1. The complexity of setting up an environment: Download stylesheets, download 
toolchain (which includes numerous choices), create a directory structure for 
your own document.

2. The complexity of customizing the default look of the documents, which look 
OK, but don't look as good as they would need to be to be put in front of a 
client.

There clearly was, and still remains a need for Docbook. If you are supporting 
a technical project, the language itself meets most, if not all of your 
requirements outside the box.

But when I see the examples that have been provided as a result of the original 
question, I see documents that range from amazing to pretty ordinary. This not 
only shows the strength of the platform, but also the weakness.

As a Docbook user, and advocate, the amazing documents antagonize me the most, 
because I'm not sure I have the time and the will to understand how they were 
created.

The question remains unanswered, having learned the Docbook language, why 
should somebody then have to face a much greater challenge to produce a 
document that looks presentable?

Does anybody sell a commercial Docbook customization layer? If this was Joomla, 
or Wordpress, or MediaWiki there would be a whole marketplace of free and 
commercial presentation layers.

Is Docbook really that obscure?

Gerard

-Original Message-
From: Thomas Schraitle [mailto:tom_s...@web.de] 
Sent: Sunday, September 13, 2015 5:39 AM
To: docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] Show off what you've done with Docbook

Hi Gerhard,

Am Samstag, 12. September 2015, 11:35:11 schrieb Gerard Nicol:
> I'm surprised nobody has put together a Linux VM image with Git and 
> Docbook etc.

Shouldn't be too difficult. ;)


> I'd happily pay a few thousand a year for a subscription to a hosted 
> or packaged Docbook environment if the results looked as good as some 
> of the better examples provided.

You can look at some of our examples which we created by our DAPS toolchain, 
here PDF:

* http://opensuse.github.io/daps/doc/pdf/art.daps.quick_color_en.pdf
*
https://www.suse.com/documentation/sles-12/pdfdoc/book_sle_admin/book_sle_admin.pdf


Of course, it is a customization layer on top of the original DocBook XSL 
stylesheets. :-) Meanwhile they are quite complicated now.

The stylesheets are released in GitHub: https://github.com/openSUSE/suse-xsl


-- 
Gruß/Regards
  Thomas Schraitle


-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org



-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Show off what you've done with Docbook

[Gerard Nicol]

I'm surprised nobody has put together a Linux VM image with Git and Docbook 
etc. 

The reason people fork out $2000 plus for RoboHelp is that it kind of works out 
of the box. 

I'd happily pay a few thousand a year for a subscription to a hosted or 
packaged Docbook environment if the results looked as good as some of the 
better examples provided. 

Sent from my iPhone

> On Sep 12, 2015, at 11:26 AM, natk  wrote:
> 
> I agree that the power of docbook is in its ability to generate multiple 
> formats.
> 
> At my last position I generated single and multi-page HTML and PDF for a 
> multi-product, multi-version docset. (I'm sorry, I'm not able to provide a 
> public URL here).
> 
> It did involve a fair amount of work, and I agree that when there is an issue 
> it can be complicated to track down and fix. The bits I found particularly 
> tricky were wrapping text (in tables mainly) so that the PDF text stayed 
> inside its margins, and the PDF cross-references. Can go into some more 
> detail on this if you like.
> 
> Bob's book and the support on these lists is awesome though - and there 
> wasn't a problem that I couldn't eventually fix.
> 
> I would also +1 the advantages of having a tool-chain that can be 
> incorporated into CI. We used svn/maven/docbkx-tools/jenkins plus some other 
> in-house tools.
> 
> Nat 
> 
>> On Fri, Sep 11, 2015 at 9:56 AM, Katie Welles  wrote:
>> It’s been a while since I’ve used Docbook or participated in this forum.
>> 
>> I used Docbook a number of years ago to put together a web-based API 
>> reference system. To be frank, I found it to be a pretty painful project, 
>> but mainly because I thought it was downright foolish to jump through all 
>> those Docbook hoops just to output simple HTML. It seems to me that the 
>> power of Docbook is when your single XML source is used for multiple outputs.
>> 
>> I support a consortium that manages 12+ open APIs, and we’ve been 
>> re-examining the tools we use to output published specs. We know we want 
>> **all** our API specs to be available as PDF and also HTML, but are not sure 
>> which tool to bank on. So far we’ve been looking at asciidoc, which I find 
>> pretty underwhelming.
>> 
>> Have any of you PDF + HTML output with Docbook? If anyone has such a project 
>> and will be willing to show it off, send some URLs!
>> 
>> As an aside: Have any of you used asciidoc?
>> 
>> (BTW — I use MadCap Flare for another of my clients. The output is 
>> stunningly beautiful, but the tool is far too unwieldy and expensive for me 
>> to be able to recommend it to my API client.)
>> -
>> To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
>> For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
> 

RE: [docbook-apps] Show off what you've done with Docbook

[Gerard Nicol]

Nils,

 

What stylesheets were used to generate the documentation at  
 http://docs.openstack.org/ with the table of 
contents on the right and the search box etc at the top?

 

It would be great if there was a cookbook for producing documentation that 
looked that good.

 

Gerard

 

From: cordb...@gmail.com [mailto:cordb...@gmail.com] On Behalf Of Nils Cordes
Sent: Friday, September 11, 2015 12:33 PM
To: Katie Welles 
Cc: docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] Show off what you've done with Docbook

 

Example projects using DocBook for documentation:

 

OpenStack Documentation: http://docs.openstack.org/

 

DAPS (OpenSuse): http://opensuse.github.io/daps/doc/index.html

 

PHP Documentation: http://php.net/manual/en/

 

Eclipse Jetty: http://www.eclipse.org/jetty/documentation/

 

XÖV-STANDARDS UND -VORHABEN: 
http://www.xoev.de/sixcms/detail.php?gsid=bremen83.c.11430.de

RE: [docbook-apps] Show off what you've done with Docbook

[Gerard Nicol]

Katie,

 

While we are being frank, I have tried so many documentation options over the 
years that I have lost count.

 

The only one I liked using was IBM’s DCF, and that was 25 years ago.

 

Docbook comes close to DCF/Bookmaster, but it isn’t quite there.

 

The main criticism I have of Docbook is that it is incredibly complicated on 
the back end and when you hit a bug it’s beyond the abilities of even those who 
call themselves Docbook experts to fix.

 

I have tried various Wikis, Word and Adobe Robohelp, and it’s a competition 
between Word and Robohelp for last position.

 

The real strength of Docbook is that it’s part of a tool chain, so I have it 
hooked into Git, and whenever I get time to work on documentation I just update 
the Docbook file I am working on and push the change. When I push the change, 
Git runs the hook and rebuilds my documents in both HTML and PDF on a machine I 
have running at DigitalOcean.

 

So, from my perspective, the power of Docbook isn’t just the documents it 
creates, it’s the fact that it is the only tool I know of that I can use as 
part of a toolchain.

 

I develop and support a very specialized tool, and over the years I have all 
but given up on ever finding a technical writer I can work with. To be honest, 
the best thing for me about Docbook is that I have decided that unless someone 
can use Docbook they are not qualified to document my product. This means I end 
up writing my own manuals, but it also means I don’t waste time and money 
working with people who write content that I end up deleting.

 

Here is an example of one of my manuals

 

http://documentation-us.gazillabyte.com/book_sync.pdf

 

Hope that helps.

 




Gerard Nicol / CEO

 <mailto:gerard.ni...@gazillabyte.com> gerard.ni...@gazillabyte.com

 

GazillaByte LLC 

4600 S. Syracuse Street, Level 9, Suite 905, Denver Colorado USA

Cell +1-720-382-8560 / Office +1-720-583-8880

 <http://tapetrack.com/> http://tapetrack.com

Languages English

 

While I am always happy to answer technical support questions, I am a regular 
traveler and may not always be able to respond as quickly as I would like. If 
you send your technical support questions to  <mailto:supp...@gazillabyte.com> 
supp...@gazillabyte.com, a support case will be automatically created and you 
may get faster service.

-Original Message-
From: Katie Welles [mailto:ka...@inkwelle.com] 
Sent: Friday, September 11, 2015 10:57 AM
To: docbook-apps@lists.oasis-open.org
Subject: [docbook-apps] Show off what you've done with Docbook

 

It’s been a while since I’ve used Docbook or participated in this forum. 

 

I used Docbook a number of years ago to put together a web-based API reference 
system. To be frank, I found it to be a pretty painful project, but mainly 
because I thought it was downright foolish to jump through all those Docbook 
hoops just to output simple HTML. It seems to me that the power of Docbook is 
when your single XML source is used for multiple outputs.

 

I support a consortium that manages 12+ open APIs, and we’ve been re-examining 
the tools we use to output published specs. We know we want **all** our API 
specs to be available as PDF and also HTML, but are not sure which tool to bank 
on. So far we’ve been looking at asciidoc, which I find pretty underwhelming.

 

Have any of you PDF + HTML output with Docbook? If anyone has such a project 
and will be willing to show it off, send some URLs!

 

As an aside: Have any of you used asciidoc? 

 

(BTW — I use MadCap Flare for another of my clients. The output is stunningly 
beautiful, but the tool is far too unwieldy and expensive for me to be able to 
recommend it to my API client.)

-

To unsubscribe, e-mail:  <mailto:docbook-apps-unsubscr...@lists.oasis-open.org> 
docbook-apps-unsubscr...@lists.oasis-open.org

For additional commands, e-mail:  
<mailto:docbook-apps-h...@lists.oasis-open.org> 
docbook-apps-h...@lists.oasis-open.org