Date: prev next · Thread: first prev next last
2015 Archives by date, by thread · List index


Em qua 29 jul 2015, às 16:29:52, Regina Henschel escreveu:
Hi Olivier,

I will answer here, because it starts private. But I think, the
discussion should be on dev@.

Agree. But I am sending this mail from a mail account that will require clearance from the 
moderator.


Olivier Hallot schrieb:
[..]

Thank you indeed for reviewing the patch. I actually wrote it to trigger
/ check the process of writing documentation and help files. So far, I
am not happy with the amount of work it takes to write a single page. I
took the whole weekend at this single page.

Yes, I know the amount of work. I've already written some pages for AOO.

Of course, we should split it into 3 issues: The help content(HC), the
content of the page and the tool HelpAuthoring (HA).

The HC:

These XHP files are really bad to work with. I can't figure an advantage
to use this technology. My question currently is: why not use ODF
itself? Or HTML? Why do we need HA and a lot of fine tuning inside the
xml blob?.

I don't know, why the XML format had been chosen originally. I have no
problem with it. Another format would need a new concept for providing
extended tips, context sensitive F1 and TOC/Index/Search of the help.

I think HelpAuthoring in its current state is not really useful.

It is good to start writing the content but the fine tune of the page must go thru the xml 
directly.



So does it worth to store HC as ODF and have a tool to just transform it
into XHP or even have a tools that picks the ODF and display it right
away when F1 is pressed?

I do not think ODF is useful here, because it has a large overhead.
HTML5 might be possible. But does it become easier? You would need to
write that kind of html directly, which is now produced by the xsl
transformation.

ODF make contributors/community life easier to insert/maintain contents. Nothing more, 
saddly.


The Content of the page

Beside the fact that HA is not totally synched with HC features (I'll
come back later), writing a help page is far from trivial as one need
knowledge on the topic but also need to know the tricks of bookmarking,
indexing, ahelp, sections, embedding and a way to understand how HC was
distributed among files and modules.

I agree on that, and without such knowledge HelpAuthoring is not usable.

In the specific topic of the Basic IDE options, all I had at hand was my
own knowledge in Basic, throughout testing of the feature and a couple
of slides I found from Miklos Vajna when he presented the GSoC matter in
Milan. That is not very much, no? Holly Google...

I have looked through those slides from the link in your answer to my
comment in the file. They have not enough information to write help
pages. For me the feature itself is not ready. Making brackets, quotes,
sub and function pairs is OK, but the code completion does not really
work, see https://bugs.documentfoundation.org/show_bug.cgi?id=92964. QA
testing is obviously missing. The feature is not ready to leave
"experimental" state.

Well the $subject patch has a warning on the experimental aspect of the feature... 


The HA tool

HA is not totally synch'ed wth the HelpContent current features of
LibreOffice. It looks like the template need to be updated: For
instance, you mention "keycode" character style, which is ignored by the
template and wiped out by HA on a roundtrip edition. Another issue I
could'nt fix is that paragraph with "role=basicode" should display with
colored fonts depending on the keywords and that does not happened with
the sample we are reviewing.

It is role="bascode" not role="basicode".

Context


Privacy Policy | Impressum (Legal Info) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Creative Commons Attribution-Share Alike 3.0 License. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License (MPLv2). "LibreOffice" and "The Document Foundation" are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy.