HTML versions of the Guides

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.

Hi

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

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

Generation of pdf is easy for LO, under FILE >> Export as PDF in Writer
and you have your pdf. I would do this after the document has been
finalized for release. We can plug this feature, saying something "pdf
files where generated using LO ...." This will tell people the can
generate a pdf file for LO without having to prep it for import into
Acrobat or use Acrobat to generate the document.

When friends ask about getting Acrobat, I tell them to use the export
feature in LO/OOo instead and save the money. The feature has been OOo
for several years and is one of the reasons I would use OOo and now LO.

An Adobe Acrobat Professional PDF can be generated/converted from another PDF (say, a PDF ported from an ODT file) so as to allow the Comment and Review (aka Comment and Analysis) functionality for any user with the ubiquitous Adobe Reader. Then, any reader (using Adobe Reader) of that enabled PDF can easily make and save any comments, notes, highlighting, etc. directly to the enabled PDF for his own use. A PDF not so enabled cannot be so readily "edited" by everyday, ordinary readers.

Therefore, I suggest that every OOo/LO PDF file be so converted by Adobe Acrobat Professional afterward, prior to release so that OOo/LO users will have that extra functionality. It only takes a few extra seconds to convert a PDF by Acrobat Professional.

It seems foolish not to so enable them for the Comment and Review function, considering its ease to do so with no added cost or real time and effort...

Gary

Hi Gary,

Therefore, I suggest that every OOo/LO PDF file be so converted by
Adobe Acrobat Professional afterward, prior to release so that
OOo/LO users will have that extra functionality.

What purpose do you want this functionality for?

...
It seems foolish not to so enable them for the Comment and Review
function, considering its ease to do so with no added cost or real
time and effort...

But for what purpose?

Nino