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

[natk]

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]

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

[Warren Block]

On Fri, 11 Sep 2015, Warren Block wrote:

On Fri, 11 Sep 2015, Katie Welles wrote:

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!


We use it for most of the FreeBSD documentation:
https://www.freebsd.org/docs/books.html

The FreeBSD Handbook is the most famous:
https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/



The Porter's Handbook is also a full book:
https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/index.html

We also have a book for people contributing to the documentation:
https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html

DocBook, XSLT, and Fop are used to generate HTML, PDF, plain text, 
PostScript, RTF, and some compressed versions of those.


For comparison, PDFs (zip-compressed) of the documents above:
ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/handbook/book.pdf.zip
ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/porters-handbook/book.pdf.zip
ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/fdp-primer/book.pdf.zip


As an aside: Have any of you used asciidoc?


I use AsciiDoc for my own articles:
http://www.wonkity.com/~wblock/docs/


These articles all have both HTML and PDF links.

-
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

[Warren Block]

On Sat, 12 Sep 2015, Warren Block wrote:

We use DocBook for all of our books and articles on FreeBSD.  Please feel 
free to check out the docs section in my previous message.  Our doc group is 
small but we welcome the chance to share and learn from others. We have an 
open mailing list (no subscription required) at freebsd-...@freebsd.org, and 
#bsddocs on EFnet on IRC.


For that matter, I'll be at the Open Help conference coming up at the end of 
the month in Cincinnati: https://conf.openhelp.cc/


Sorry, got distracted before adding that if anyone wants to meet up 
during that conference, it would be great to talk about docs, DocBook, 
AsciiDoc, and other tools.  The conference itself is well worth 
attending for anyone who writes documentation, and is over the weekend. 
I'll also be there for the first day of the sprints on Monday, when 
there will likely be more one-on-one time available.


-
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

[Warren Block]

On Fri, 11 Sep 2015, Gerard Nicol wrote:



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.


Heh.  Word is what drove me to start using the FreeBSD doc tools back 
when it was still DocBook SGML.



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.


That would work with AsciiDoc or RST or Markdown also, wouldn't it?  Not 
that I'm saying those tools are superior, just that they are also simple 
markup languages.  (DocBook's markup is simple, it's just so... rich.)



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.


We use DocBook for all of our books and articles on FreeBSD.  Please 
feel free to check out the docs section in my previous message.  Our doc 
group is small but we welcome the chance to share and learn from others. 
We have an open mailing list (no subscription required) at 
freebsd-...@freebsd.org, and #bsddocs on EFnet on IRC.


For that matter, I'll be at the Open Help conference coming up at the 
end of the month in Cincinnati: https://conf.openhelp.cc/



Here is an example of one of my manuals

 

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

 

Hope that helps.

 

Logo

Gerard Nicol / CEO

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

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 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: 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

[Nils Cordes]

The OpenStack Documetation uses the Apache Maven CloudDocs Plugin (a fork
of Docbkx Tools).

Apache Maven CloudDocs Plugin
https://github.com/rackerlabs/clouddocs-maven-plugin
http://mvnrepository.com/artifact/com.rackspace.cloud.api/clouddocs-maven-plugin/2.1.4

OpenStack API Writers Guide
http://docs.rackspace.com/writers-guide/content/index.html

OpenStack Wiki Documentation HowTo
https://wiki.openstack.org/wiki/Documentation/HowTo



2015-09-12 6:03 GMT+02:00 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

[Martin Doucha]

Dne 11.9.2015 v 18:56 Katie Welles napsal(a):
> 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!

I've used Docbook to translate a book and generate print-quality PDF,
HTML and EPUB. Download links including Docbook/XSL sources are in the
small box on the right on the official project website (in Czech):
http://swarmwise.pirati.cz/

Regrads,
Martin Doucha



signature.asc
Description: OpenPGP digital signature

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

[John W. Shipman]

On 09/11/2015 12:56 PM, Katie Welles wrote:
+--
| 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!
+--

I've been using DocBook as a vehicle for literate programming
for well over ten years now.  Here are several dozen examples
including one suite that contains roughly 50k lines of Python:

http://www.nmt.edu/~shipman/soft/litprog/

Here's my stylesheet customization layer, also a literate program:

http://www.nmt.edu/~shipman/doc/doc5style/

There is a reason for having both PDF and HTML output that I
rarely see mentioned.

When I read documentation for a tool I want to use, I want to be
sure that I've read or at least skimmed the complete
documentation.  Too often in my novice days I would read a
little, try to use the tool, and find out later that features
discussed in one of the parts I skipped could have made life much
easier.

A chunked HTML rendering is very convenient, but sometimes when
I'm clicking around a heavily cross-linked structure, I have to
wonder if I've seen all the content, especially if the HTML does
not provide a table of contents.  With a PDF, I can read (or
skim) the whole thing sequentially and be confident that I didn't
miss anything.

I am extremely grateful to the people who built DocBook, and
most especially to Norman Walsh who build the modular stylesheets,
and the indispensable Bob Stayton without whom I could never have
built a presentable style.

Happy documenting,
John Shipman (j...@nmt.edu), Adjunct Professor of Computer Science
Cramer 212, New Mexico Tech, Socorro, NM 87801 (505)249-3839


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