HTML versions of the Guides

Documentation General
#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.

#28

Hi :slight_smile:
Most places that have any kind of leaflet, posters or documentation to download
want to have some control over the way it looks. Sadly there is not an adequate
Open Document Format so people use PDF. Since PDF is so widely used it forces
everyone to use it. I don't think we can make a stand against that right now.
We have to use PDF or else marginalise ourselves.

Most places that do have pdfs to download also have a button to the Adobe site
to download their latest reader (for free) in case people can't read pdfs even
though that is desperately unlikely. I think we should have a similar button
but perhaps we could choose someone other than Adobe?

I think we should also follow that lead and have a button leading people to a
stable ODT reader, not our 3.4.x releases!
Regards from
Tom :slight_smile:

#29

Hi Jean

We are essentially saying the same thing. For necessary files where the ODF cannot be read due to the inability of having LibreOffice installed to read ODF files then falling back on .pdf's is fine. If there is a need to create a quick and dirty ODF reader, then we should put this to the dev's as a project -- a "LibreOffice Reader". We should not be advocating the use of any other format unless we really have to. If our documents are so important for a user to want to read, then they should download our product to read our wonderful manuals.

Otherwise, we relegate the ODF (and LibreOffice) to a secondary position -- there will always be individuals inside our group who will clamour for a .pdf version to add "universality" to our product line. This is completely counter-productive. The request for .pdf will never cease and all of our documentation will be in ODF/PDF versions with no real reason to fully adopt the ODF format by any user. Worse, corporate adoption of our product will be hard to get if they will never see the benefits of using our products if they only read it through .pdf formats for their convenience. It is difficult to issue accolades to a product that second guesses itself to its intended user base. If pdf's are so necessary, then people should be looking for a .pdf office suite as everyone extolls its virtues.

I don't think Adobe would ever suggest to anyone else to use a different format for people to read their manuals, they would of course tell all to download their reader and to then read their wonderful manuals.

We should do the same, as we do have the better format of the two. The use of .dpf's should be done in a very strategic way and not in a universally applied fashion.

All of my opinions.

Cheers

Marc

#30

Hi :slight_smile:
You have 6 seconds and 3 mouse-clicks to grab & hold a persons attention before
they leave the website. Demanding that they download and install an unfamiliar
product pushes people away unless the entire process is completed in under that
time.

People on an early visit may just open documentation just to see that it's there
and easy to access, looks reasonably up-to-date, 'professional' and easy to
use. The slightest thing could put people off. Deliberately making
documentation difficult to access is unlikely to be of benefit with market
penetration as low as it is in English speaking countries. Once we reach 20%,
as in Europe, then it is a more viable proposition.

Regards from
Tom :slight_smile:

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