Re: Publishing / typesetting print documentation in HTML + CSS (+JS)

Subject: Re: Publishing / typesetting print documentation in HTML + CSS (+JS)
From: John Allred <jack -at- allrednet -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Sun, 14 Aug 2011 20:55:40 -0500

At some point, someone here is going to slap my wrist for posting
things just a little too far off the topic and just a little too long.
I think Richard covered the question you asked pretty well, Jimmy. So,
I would hope, there is some slack for stretching out on this particular
topic. The only thing I would add to Richard's response is that even
CSS 3.0 is a poor tool for producing text truly intended for a print
format. For your desktop printer, or for other informal documents, it's
fine. But for any structured document--book, magazine, newsletter, user
documentation--where layout of the page is critical, there are precious
few controls for crafting a well-laid out document. Try kerning text or
wrapping text around an irregularly-shaped object using HTML/CSS. Try
creating dynamic, running headers or footers.
Conversations here have spasmed over the different ways to try to
handle the nesting of numbered bullets. It's far easier to take a
document developed for print and port it to HTML. For PDF output, it's
as simple as hitting the Print button. Your page layout or--god
forbid--word processing app has taken care of the formatting to a
particular paper size already. The idea of going the other way, except
for churning out queries of raw data and producing a PDF on the fly
from the web server, baffles me. It's useful to remember that,
nowadays, the vast majority of content has no real structure and can be
presented sloppily and informally, and no one will much care. So
porting a web page to print is probably no longer a concern except to a
few craftsmen.
Jimmy, what you're asking about takes me back some 25-30 years. Way
back, before the World Wide Web and HTML, and before Desktop
Publishing, even, there was an esoteric language known as SGML, which
stands for Standard Generalized Markup Language. While SGML is still an
integral part of the WWW family of languages, its inception was in
printing. I never used it directly, but I was aware of it soon after my
entry into DTP with Ventura Publisher's version 2. SGML was developed
for newspapers, magazines and books. But, it contributed strongly to
what we now know as XML. eXtensible Markup Language. Kinda has a ring
to it.
When Ventura Publisher (VP) was originally developed at Xerox PARC, it
made use of this language under the hood, but it didn't give the user
direct access to it. Because of this power of structure, Ventura
Publisher became the king of PC-based publishing. It had incredible
power to control every nuance of page layout using definable rules,
which it, and every other application since has called Tags. Nothing on
the Mac ever rivaled its power in the first decade or so. VP survived
several owners, including Corel, until its final release in 2002 as
Version 10. Many awful, but popular, packages, like Aldus PageMaker
and QuarkXpress, required expensive add-on "extensions" in order to
address the needs of structured text. In spite of having these add-ons
available, they didn't do structure well.
VP made attempts through its middle years, as did many other DTP
packages, to export DTP content to multiple platforms, using a single
source document. Remember, for my rant later, that this is what we're
talking about in this thread. The implementations of this, including
VP's, were poor, partly due to the Wild West state of HTML in those
days. With Microsoft ignoring nearly everything the W3C proposed as
standards, pulling a usable set of rules together for everybody was all
but impossible. The worst implementation, also IMNSHO, was Microsoft
Word writing a unique CSS class for every jot and squiggle on a page.
Fine for displaying in other MS apps, if uncontrollable document bloat
is no issue for you. Useless for any other purpose, though. Microsoft
has never played nice with anybody else and probably never will.
I know there are new applications that incorporate some of this ability
to repurpose content to different platforms. In my mind, though, we
missed a golden moment more than 20 years ago. That was a time when the
raw, naked profit motive pushed progress backward rather than forward.
I'm not sure we'll ever fully recover that opportunity for a
standards-based world of publishing. With Microsoft finally starting to
behave itself in IE version 9.x, there's hope, at least, for the Web.
Consider yourselves lucky. I could give you more snotty opinions about
all the bad boys in DTP and the Web than you have time to read.
Microsoft almost succeeded in killing the promise of the web, too, but
has finally lost that fight to the momentum of intelligence and
imagination. Not that they wanted, really, to kill the web. They just
want to own it, lock, stock, and barrel. I take comfort in knowing that
Microsoft's attempts at document publishing and web publishing, both,
suffered ignominious deaths.
* The article at [1]http://en.wikipedia.org/wiki/Ventura_publisher
leaves out much important detail, particularly about how SGML
influenced the development of Ventura Publisher, which inspired the
DTP industry, despite Aldus PageMaker's claim to that distinction.
* [2]http://en.wikipedia.org/wiki/PARC_%28company%29 Mac people
believe, and would try to convince you, that Apple invented the
GUI, DTP, and all the other things we love about computers today.
In fact, Xerox PARC did the inventing. There was a furious exchange
of contracts, ideas, cooperation and lawsuits among PARC, Microsoft
and Apple over all of this. PARC, which also developed Ventura
Publisher, invented all this stuff. Apple got to the market with it
first, that's all.
* [3]http://personal.dvint.com/publications.xml (Published 1998)

<END OF RANT SUMMARY> Mostly, I've been singing the praises of a now
defunct piece of software and a few companies that had a vision for the
world of publishing, no matter the particular implementation--paper,
web, PDA, multimedia, etc. Because of greed and stupidity, we now face
the same problems we had 25 years ago, only now we have hundreds of
different software applications, each trying to tear off a tiny piece
of a huge, confused market. The chance to unify this field with
kick-ass software and make your job as a technical writer one,
primarily, of writing, without regard to technical niceties of
presentation, are long gone. Thank you Microsoft and Adobe. Sorry I
didn't buy some stock in your sorry companies years ago. At least I
could have profited from your short-sightedness.</END Of RANT SUMMARY>
~john allred
On 8/14/2011 6:37 PM, Richard L Hamilton wrote:

Jimmy, little be

Looking again at your message, I would suggest that you look closely at what's a
vailable with the DocBook and DITA schemas. You will find that a lot of the work
you may be thinking of doing has already been implemented for these two schemas
. Both have active communities that support toolkits that will get you from XML
to html, print, ebooks, and various help formats, and both toolkits allow you to
customize output in a variety of ways.

You can get from HTML to print, but it's not the easiest way to go in my experie
nce. The only times I've done a book from HTML, I converted the HTML to DocBook
XML and used that toolchain, rather than CSS. There are folks who can do magic w
ith CSS and who would probably disagree with me, but if you're starting with XML
, rather than HTML, I would do what I suggested in my previous message and go di
rectly with whatever toolkit exists for the schema you choose.

Good Luck,

Richard Hamilton
-------
XML Press
XML for Technical Communicators
[4]http://xmlpress.net
[5]hamilton -at- xmlpress -dot- net

On Aug 14, 2011, at 5:05 AM, Jimmy Breck-McKye wrote:


Does anyone here have any experience publishing paper documentation using HTML a
nd CSS?
Because my job involves testing and diagnosing problems in web applications, I'v
e an awful lot of opportunities to learn about these technologies. It makes sens
e to learn one, versatile tool well rather than two poorly. It also makes sense
to use technologies that are well-documented and easily understood by my peers.
CSS helps me tick all these boxes.Practically speaking, I'm told that print CSS
handling is quite mature on certain browsers, and from what I've seen, it looks
as though CSS can do an awful lot. It also looks pretty straightforward to imple
ment an XML - XSLT - HTML + CSS toolchain (as much as XSLT's syntax irritates me
). Working in plain XML would free me to implement parts of my toolchain in othe
r technologies, too (I've had especially good experiences transforming XML with
Python scripts).But that's just the theory. Does anyone have any practical exper
ience on this point? Any advice or common pitfalls?Thanks in advance,Jimmy/p>(Al
so, apologies if the carri
ag

e

returns are broken. The Techwr-l mail handler seems to have a particular issue w
ith my emails)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
[6]http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as [7]dick -at- rlhamilton -dot- net -dot-

To unsubscribe send a blank email to
[8]techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit [9]http://lists.techwr-l.com/mailman/options/techwr-l/dick%40rlhamilton
.net


To subscribe, send a blank email to [10]techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to [11]admin -at- techwr-l -dot- com -dot- Visit
[12]http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
[13]http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
[14]http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as [15]jack -at- allrednet -dot- com -dot-

To unsubscribe send a blank email to
[16]techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit [17]http://lists.techwr-l.com/mailman/options/techwr-l/jack%40allrednet
.com


To subscribe, send a blank email to [18]techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to [19]admin -at- techwr-l -dot- com -dot- Visit
[20]http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
[21]http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat

References

1. http://en.wikipedia.org/wiki/Ventura_publisher
2. http://en.wikipedia.org/wiki/PARC_%28company%29
3. http://personal.dvint.com/publications.xml
4. http://xmlpress.net/
5. mailto:hamilton -at- xmlpress -dot- net
6. http://www.doctohelp.com/
7. mailto:dick -at- rlhamilton -dot- net
8. mailto:techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
9. http://lists.techwr-l.com/mailman/options/techwr-l/dick%40rlhamilton.net
10. mailto:techwr-l-join -at- lists -dot- techwr-l -dot- com
11. mailto:admin -at- techwr-l -dot- com
12. http://www.techwr-l.com/
13. http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
14. http://www.doctohelp.com/
15. mailto:jack -at- allrednet -dot- com
16. mailto:techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
17. http://lists.techwr-l.com/mailman/options/techwr-l/jack%40allrednet.com
18. mailto:techwr-l-join -at- lists -dot- techwr-l -dot- com
19. mailto:admin -at- techwr-l -dot- com
20. http://www.techwr-l.com/
21. http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


References:
Publishing / typesetting print documentation in HTML + CSS (+JS): From: Jimmy Breck-McKye
Re: Publishing / typesetting print documentation in HTML + CSS (+JS): From: Richard L Hamilton

Previous by Author: Re: Advice on software testing?
Next by Author: Re: New words - where have you found them?
Previous by Thread: Re: Publishing / typesetting print documentation in HTML + CSS (+JS)
Next by Thread: RE: Evaluation Process - HATs


What this post helpful? Share it with friends and colleagues:


Sponsored Ads