HTML versions of the Guides

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

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

--Jean

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

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

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

--Jean

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

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:

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

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.

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

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

--Jean

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.

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:

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

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:

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.

PDF has a different purpose: to show a document in identical layout on
any output media.

ODF in contrast is the preferred data format for supporting all kinds of
documents needed in an office environment.

To support office productivity is a substantially different aspect from
supporting media independant layout.

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.

This ist questionable, sorry.

To use a complex software, you need as much help and support as
possible. This is true on any level of skill. So no software supplier
would leave out e.g. online help and state that anybody should read only
ODF/PDF/whatever Manuals. Nobody would ignore wikis when trying to solve
a problem because they are not ODF formatted. Or forums or mailinglists
or whatever. Where do you live?

We have to help the users to use the software best possible (and not to
force them to use a certain output format if seeking help, what strange
ideas do you people have?!)!

For that, IMHO our ambition should be to offer the Manuals in as many
formats as possible, so a user can decide which suites best his/her
actual needs.

So my statement would be:
Stay with ODF as master (as long as there is not a more conveniant
solution) and try to offer PDF /and/ HTML in addition. Ideally, the PDF
and HTML conversion should be done as automatically as possible, so no
need for additional manpower.

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.

ODF does have different advantages. Competing with PDF is not among
them. Or at least, not yet. If the ESC decides to take that challenge,
it might be an option in the future. But ATM it's out of scope IMHO.

Nino

You've hit in an important point Nino. The doc team does not have the
manpower available to create and maintain independent documentation
streams. HTML is a fine idea, but not as a leading/primary format.
If there is a need for HTML, then do it as an output/publishing format
from the ODT sources.

Clayton

I agree with ODF formats for our documentation and then other versions
as needed latter. When they are made, when can state the where
saved/exported for the LO, plugging some of the other capabilities of
LO.

I would not use htiml unless someone cleans up the code. Most program
generated html I have seen is very difficult to follow, debug, and
maintain without someone cleaning it up. Ofteh I have found myself
redoing the pages with hand coding only.

________________________________
From: planas <jslozier@gmail.com>
To: documentation@global.libreoffice.org
Sent: Thu, 23 June, 2011 16:16:48
Subject: Re: [libreoffice-documentation] HTML versions of the Guides

On Thu, 2011-06-23 at 04:27 -0400, Marc Paré wrote:

Le 2011-06-23 02:30, David Nelson a écrit :
> 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.
>
> --
> David Nelson
>
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

--
Marc Paré
http://www.parEntreprise.com

I agree with ODF formats for our documentation and then other versions
as needed latter. When they are made, when can state the where
saved/exported for the LO, plugging some of the other capabilities of
LO.

I would not use htiml unless someone cleans up the code. Most program
generated html I have seen is very difficult to follow, debug, and
maintain without someone cleaning it up. Ofteh I have found myself
redoing the pages with hand coding only.

Jay Lozier
jslozier@gmail.com

Hi :slight_smile:
+1
Except that i get over-excited about allowing people access easily so i fall
into rants about needing pdf too lol. Sorry about that Marc! I know Adobe and
MS both achieved market dominance partly through non-compliance but since they
achieved domination it's difficult to disrupt that. I think we have to pick
fights we can win first.

Regards from
Tom :slight_smile:

Hi

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:

________________________________
From: Marc Paré <marc@marcpare.com>
To: documentation@global.libreoffice.org
Sent: Thu, 23 June, 2011 9:27:00
Subject: Re: [libreoffice-documentation] HTML versions of the Guides

> 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.
>
> --
> David Nelson
>
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

-- Marc Paré
http://www.parEntreprise.com

-- Unsubscribe instructions: E-mail to documentation+help@global.libreoffice.org
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted

True most people are conditioned to look a pdf file. But one save LO
documents with a password which maintains version/document control. This
feature is (also in MSO) is rarely used, I think because most people are
not aware of it. The Acrobat Reader is a marketing tool for Adobe to
make pdf popular and improve sales of the Acrobat. There are currently
several free readers for Linux and Windows. Some are considered better
than Reader itself. Maybe instead of link to Adobe we have a link, if
possible, to a FOSS pdf reader. People can still read the pdf and we
promote some sister projects.

What some have done to get around needing Acrobat to prepare pdf's is
use a suite like LO that can export the document as a pdf. Any pdf
generated we need can be done in LO and we state that on the page. Any
time we revise the document we do it using LO. I have been aware of this
feature in OOo/SO for many years when MSO did not have it.