HTML versions of the Guides

Documentation General
#8

Another major plus for PDFs is that any Adobe Acrobat Professional versions from around Acrobat 6 (of yesteryear...) can enable a very useful functionality to PDFs so that anybody with the free Adobe Reader can make markup directly upon the PDFs. I employ that functionality with nearly all my clients for the PDFs I make, whether they are works-in-process, finished projects, or simple copyediting runs.

To demonstrate that, I will take the PDF version of the Writer Guide and, using Acrobat Professional, will impart that functionality to it, so that any user with Abode Reader can easily do such markup on it. Adobe calls that Comment and Review (or more recently, Comment and Analysis), in case anybody cares to conduct a web search on the subject.

Gary

#9

Hi :slight_smile:
I think the ODF guides do most of what you want from html ones. The pdfs are
good but the odfs are more flexible.
Regards from
Tom :slight_smile:

Each format serves the needs of different audiences. The PDFs are
primarily for the many people who want to print pages for reference, and
for those people who need an offline manual, something they can store on
their computer for use when they are not connected to the internet. PDFs
are also good for people who have not yet installed LibreOffice or OOo
or who might need to look up something on a machine that doesn't have
LibO or OOo on it.

HTML is great for people who prefer to read stuff online and are able to
do so when they want the info.

I do not think ODT is suitable for most users as a reference document,
though it is fine for many and of course necessary if one wants to edit
the file. Inexperienced users can bugger up an ODT faster than you can
say "don't do that!" But they can't easily change a PDF, and they are
more likely to already know how to open and read a PDF than an ODT.

A personal example of use: While I was travelling with my iPad as my
only computer, I could easily store and read PDFs on it, or download
them when needed (when I could find a connection), but ODTs were
inconvenient. I eventually found a program that would open them (by
converting to something, HTML probably) but there were no pages and some
of the formatting was a bit messed up. If I needed or wanted to answer a
question for someone (as I did on a few occasions), it was a hassle that
PDFs avoid. When I had an internet connection, I could have looked up
something on a wiki or a website, but usually I was working offline.

I may be unusual in my working conditions, but really this is not a "one
size fits all" situation.

Errrr.... didn't mean to have that turn into a rant, but it did. :wink:

--Jean

#10

Hi John,

When checking the PDF version of the Calc guide I found it hard,
compared to html to move around the document. I would like to
propose that an HTML version is produced. I would be happy to
undertake the work.

I am not sure what open source html producers/editors are available,
but will do some research into what is available.

Does anyone else think this is a good/bad idea.

It's definitely a good idea.

An ODT uses XML, (just like e.g. DocBook) so direct HTML conversion
should be possible with just a DTD, shouldn't it?

Did you try the genuine (X)HTML Export (File > Export)?

AFAIK there are several ODF-to-HTML tools available, e.g. this one
http://opendocumentfellowship.com/projects/odftools

I think, the HTML question is not about "finding the better/best format"
but it's more about "offering an additional format", as Jean said.

So in my eyes we would be fine offering a couple of (addtional) HTML
formates (whole book and chapter wise?) for the User Guides like many of
the Linux docs have done for years. My guess is, that the ODT should
serve as Master and the HTML should be just one possible output format.

Nino

#11

A DTD (say, a DocBook 4.5 DTD--the last normative version, 03 Oct 2006) only deals with document structure--not formatting a document. So, you would have to employ something else for formatting purposes, much like CSS formats XHTML code.

In the (XML) structured world using Adobe FrameMaker, you could run FrameMaker in its structured mode using a DTD file for the XML structure and an EDD file (that a template designer must create) for formatting purposes. The EDD file would typically be imported into an FrameMaker FM file template after it had been previously structured via a DTD file, the end result is a template file that an author could then utilize for authoring purposes, utilizing whatever formatting the EDD file was programmed to provide. Not an easy task--the creation of a formatting EDD.

OOo really never did much with its so-called DocBook XML. In fact, what little it had was for the DocBook version 4.1.2, which dates back to 18 Dec 2003.

BTW, I have created EDDs based upon DocBook 4.5 and DocBook 5.x, which were generated by FrameMaker from the DocBook DTDs. Generation of formatted DocBook-XML templates for documentation-authoring purposes is typically a job for an expert, so doing documentation with DocBook is definitely not for beginners. If anybody would care for some advice using FrameMaker's DocBook 4.5 or 5.x, I could give it.

There are other software applications that could be used. Sagehill has some documentation along those lines: http://www.sagehill.net/docbookxsl/

Gary.

Gary Schnabl
Southwest Detroit, two miles NORTH! of Canada--Windsor, that is...

Technical Editor forum <http://TechnicalEditor.LivernoisYard.com/phpBB3/>

#12

On Wed, 2011-06-22, Gary Schnabl wrote about DocBook.
My view, which I have expressed on several occasions: Using DocBook
files (or anything other than ODT files) as source documents for our
user guides would be counter-productive, for two main reasons:

(1) It would exclude the vast majority of potential contributors to the
LibO documentation, who won't want to have to obtain and learn to use a
new tool; most contributors, in my experience, have enough difficulty
learning how to use Writer well.

(2) Keeping our source docs in anything other than ODTs created using
our own product is very, very bad publicity for our product.

Related reasons are: by using the product to produce documentation, our
contributors are more likely to learn how to use that product better;
and they may find bugs or identify places where the product could be
enhanced, thus assisting the developers.

I'm fine with discussing tools for producing multiple outputs (HTML, for
example) from our source ODT files. Individual members of the team who
are familiar with those tools can work from the source ODTs, but most
contributors would not need to use or understand them.

Some other forms of user docs can be produced, delivered, and maintained
on the wiki: things like tips and short how-tos. But not the user
guides. Seriously.

--Jean

#13

On Wed, 2011-06-22, Gary Schnabl wrote about DocBook.
My view, which I have expressed on several occasions: Using DocBook
files (or anything other than ODT files) as source documents for our
user guides would be counter-productive, for two main reasons:

(1) It would exclude the vast majority of potential contributors to the
LibO documentation, who won't want to have to obtain and learn to use a
new tool; most contributors, in my experience, have enough difficulty
learning how to use Writer well.

(2) Keeping our source docs in anything other than ODTs created using
our own product is very, very bad publicity for our product.

Related reasons are: by using the product to produce documentation, our
contributors are more likely to learn how to use that product better;
and they may find bugs or identify places where the product could be
enhanced, thus assisting the developers.

I'm fine with discussing tools for producing multiple outputs (HTML, for
example) from our source ODT files. Individual members of the team who
are familiar with those tools can work from the source ODTs, but most
contributors would not need to use or understand them.

Some other forms of user docs can be produced, delivered, and maintained
on the wiki: things like tips and short how-tos. But not the user
guides. Seriously.

--Jean

I wrote about a DocBook DTD file in response to Nino's bringing it up, but nowhere in this thread did I advocate using it . A careful read of my post would lead one to believe that I was discouraging the use of it. So, you needed to address the DocBook issue to Nino, not me...

Seriously.

Gary

(Nino said:

An ODT uses XML, (just like e.g. DocBook) so direct HTML conversion
should be possible with just a DTD, shouldn't it?)

#14

A DTD (say, a DocBook 4.5 DTD--the last normative version, 03 Oct
2006) only deals with document structure--not formatting a document.
So, you would have to employ something else for formatting purposes,
much like CSS formats XHTML code.

[lots of technical stuff snipped]

(Sorry, I'm really not an expert here, I just wanted to share the idea.)

Gary, my point was not to *use* DocBook but to take ODT and provide
export filters to generate HTML *like* DocBook does.

OOo really never did much with its so-called DocBook XML.

But - at least from a non-expert view like mine - DocBook seems to be
XML with chapters, paragraphs and so on, and ODT is XML with chapters,
paragraphs and so on. So at least in theory they should be mutually
convertable, shouldn't they?

So hypothetically, the DocBook-to-HTML converter should be easliy
tweakable to take ODT as input. Ok, by an advanced developer :wink:

Nino

#15

(that's the only point I wanted to make, sorry if it was not stated
clearly enough)

Nino

#16

Nino clearly said he thinks the source should be ODT, so I have no
problem with his comments about conversion tools. Your note sounded to
me like you were advocating DocBook, as you have done on several
occasions in the past, not discouraging the use of it. Apparently I
did't read your note carefully enough. Sorry.

--Jean

#17

I thought your point was quite clear. I misread Gary's note, not yours.

--Jean

#18

DocBook XML publishing might be done in a well-staffed publishing house. However, OOo or LO just does not possess neither the manpower, the time, nor the expertise to do that.

As I said, a DTD file merely provides rules for structuring a document, but does not format it. Somebody has to create a formatting file and also a template based upon the marriage between DTD and the formatting file. It is not an easy, straightforward task.

Doing some small DocBook (XML) programming and formatting with very simple files would help one to grasp the work that needs to be done, though. For that, confer the Sagehill link for documentation on how to go about that. It would be good training in the event somebody wanted to ever go that route. Personally, if I were to go the DocBook XML route, I would employ a WYSIWYG app like FrameMaker instead of apps using a command line and such. I do not working all that hard.

In any event, it is John who wanted to take on the HTML-creation task. He will soon find out that today, one or more CSS files does the XHTML formatting. (I prefer viewing PDFs over most XHTML, amyway.)

As I mentioned before, I will enable the LO Writer Guide PDF for Adobe Reader markup. That would be a good markup exercise for anybody at LO who might want to copyedit it--or proofread it, assuming it is finished. And playing with Comment and Review (analysis) is also fun to do. I will upload that enabled PDF in a day or two.

Gary

#19

Hi

When checking the PDF version of the Calc guide I found it hard, compared to html to move around the document. I would like to propose that an HTML version is produced. I would be happy to undertake the work.

I am not sure what open source html producers/editors are available, but will do some research into what is available.

Does anyone else think this is a good/bad idea.

Regards

John Cleland

If you plan to do what you plan, try using a WYSIWYG application like MS Expression (formerly FrontPage) or Adobe's DreamWeaver. Microsoft has such a free deal with its WebSpark program. You get the use of MS Visual Studio 10 and the Expression suite to use for three years for nothing--and get to keep them afterward:
http://www.microsoft.com/web/websitespark/

Gary

#20

I suspect that approach (using non-opensource software) would not go
down well with most of the LibreOffice project people. Just saying.

--Jean

#21

________________________________
From: Jean Hollis Weber <jeanweber@gmail.com>
To: documentation@global.libreoffice.org
Sent: Wed, 22 June, 2011 10:13:29
Subject: Re: [libreoffice-documentation] HTML versions of the Guides

On Wed, 2011-06-22 at 04:57 -0400, Gary Schnabl wrote:

> Hi
>
> When checking the PDF version of the Calc guide I found it hard, compared to
html to move around the document. I would like to propose that an HTML version
is produced. I would be happy to undertake the work.
>
> I am not sure what open source html producers/editors are available, but will
do some research into what is available.
>
> Does anyone else think this is a good/bad idea.
>
> Regards
>
>
> John Cleland

If you plan to do what you plan, try using a WYSIWYG application like MS
Expression (formerly FrontPage) or Adobe's DreamWeaver. Microsoft has
such a free deal with its WebSpark program. You get the use of MS Visual
Studio 10 and the Expression suite to use for three years for
nothing--and get to keep them afterward:
http://www.microsoft.com/web/websitespark/

I suspect that approach (using non-opensource software) would not go
down well with most of the LibreOffice project people. Just saying.

Jean

Hi :slight_smile:
At a guess i think the html coding is the easy part. The Odt files can be
exported to html with Writer or something and then tidied up again with Writer.
If a wysiwyg editor is needed thee are plenty of OpenSource ones but it's better
to edit the html.

The difficult parts of the plan (imo) are;
1. getting a space on the TDF servers alongside the existing documentation,
preferably in the same folder and having permissions to edit the html. There is
a security issue there.
2. Keeping the thing updated.

I think wiki-pages are a MUCH better idea. The links to headers and stuff is
done automatically and it's practically wysiwyg anyway. Also a LOT f people,
particularly people interested in documentation already know wiki-mark-up but
don't know html. Html is not difficult but many people are intimidated by it
and feel comfortable with wiki's [shrugs].
Regards from
Tom :slight_smile:

#22

Hi :slight_smile:
It is interesting to hear about free stuff from MS. One always wonders what
tricks, caveats, lock-ins and what traps are being sprung.

Regards from
Tom :slight_smile:

#23

Hi :slight_smile:
It is interesting to hear about free stuff from MS. One always wonders what
tricks, caveats, lock-ins and what traps are being sprung.

Regards from
Tom :slight_smile:

Use a little of this, a little of that... I am not a wide-eyed zealot, forcing myself to stick with only open-source applications.

Being an electrical and computer engineer, I would prefer to use the tools that work the best--even if I have to pay for them, sometimes. (I do not use any bootleg software.) Fortunately, four years ago, as an inactive beta-tester, MS gave me afterward free copies of Vista Ultimate and MS Office Professional Plus 2007, plus a few other of their apps for attending their market launch/seminar--a five-mile bus ride away. Motorola gave me a free copy of FrameMaker when I was a technical editor for them six years ago. So, I cannot complain.

I even buy legal versions of proprietary software on eBay or from the vendors--right after a new version is released. 80% discounts are common. Sometimes, they give away slightly dated versions for free.

Bargains can usually be found.

Gary

#24

Hi,

My 2 cents would be that the best format for guides is .odt, plus a
publication of the user-ready version in PDF.

I don't think an HTML version would really be a useful idea.

#25

I will chime in as well. I would rather see the ODF versions first and the .pdf only if needed. We are, after all, telling people that we have the best office suite on earth, so let's prove it! It does work!. I would even go as far as not publishing any .pdf versions. People needing documentation will have LibreOffice to read the ODF files. I would only supply .pdf files if it involved anything with the installation of LibreOffice.

Cheers

Marc

#26

Marc, please see my earlier note about the importance and necessity of
providing PDFs.

--Jean

#27

Hi,

Marc, please see my earlier note about the importance and necessity of
providing PDFs.

Yeah, I'd agree with Jean about it being important to provide PDFs.
Past discussions on this list led to a consensus that ODF's .odt
format is the best working medium but, when it comes to publishing,
it's best to publish in PDF as well, because anyone can read it, with
or without LibreOffice installed. Sure, I'm all for supporting
ODF/.odt but, even so, I don't feel we have to ram it down people's
throats. :smiley: IMHO, it's even counterproductive to be dogmatic about
it.

So, to re-state my own 2 cents, I feel it's best to work in .odt and
to publish in .odt and .pdf.

Impressum (Legal Info) | Datenschutzerklärung (Privacy Policy)   Content on this site is licensed under a Creative Commons Attribution Share Alike 3.0 license.