Re: [PATCH] TDF#80588 Help page for Basic IDE Options

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