<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd"> <html><head><meta name="qrichtext" content="1" /><style type="text/css"> p, li { white-space: pre-wrap; } </style></head><body style=" font-family:'Oxygen-Sans'; font-size:12pt; font-weight:400; font-style:normal;"> 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". I could not make help render this piece of code anyway. > > > As I wrote above, I could not work on the page without going back and > > forth into the xml. If we forget a bookmark, the tool is clumsy to fix > > it. I got some dup'ed ID's on copy&paste paragraphs (IDs are duped and > > this is a no-no), so I had to fix in the xml (perhaps we can add a macro > > do rewrite a valid ID on a paragraph, but I learn in the hard way that > > messing with paragraphs IDs will affect translators jobs.). Furthermore > > that yellow fields disturbs reading. > > > > Not to forget that I had to "make clean && make" in Helpcontent2/ to > > check the results.... > > > > The process... > > > > As we already know, writing in ODF is a piece of cake and extremely > > straightforward and comfortable. Questions left are > > > > - Continue as we are by fixing the HA tool? > > I'm not sure, that HA is of worth. It was unused in AOO for several > years, perhaps with good reason? But if the decision on dev@ would be to > use it, then I will helping to improve it. > We already went thu this and it may worth to improve it. > > - Should we take ODF as repository for help page edition (just like you > > did here in the attachment) and then work until we are happy with the > > content and then transform it to XHP to submit to gerrit? > > ODF or HTML is meaningful to control the content and appearance. I > usually provide the content to the mailing list, because I'm German and > my English always needs corrections. First ODF for content and > appearance and then xhp to Gerrit is a reasonable order for new features. Agree. But nevertherthe less I tihnk we need a repository to store these ODFs untill they are ready to move to xhp. > > A useful tool would be to get the page as shown in the help viewer > without compiling the whole helpcontent2. > Agree > In AOO I had build the helpcontent2 separately, delivered and have > thrown the result from solver into an existing installation. But that is > cumbersome too. > > > - Should we write a tool to go directly from ODF to Helpcontent (that > > is, a HA automatic) in the build process ? > > > > - Anything else? > > Such has to be discussed on dev@. Any solution has to keep the ability > of extended tips, the ability of offline help, and the ability to use > content from and deliver content to https://help.libreoffice.org. And > the change has to be more or less automatic, because you cannot handle > about 3600 files with -I estimate- 10000 helpIDs manually. I think, it > is a hard task. > > What do you think about a guide to create and edit xhp-files, placed in > the Wiki? I mean bringing OOo2HelpAuthoring.pdf to the Wiki, update it > where necessary and enrich it with further examples and additional > informations. Agree with you... My sole concern is that this is a extensive task (time consuming) and I am short of time. > > > Full of questions and scarse time to address it. > > > > Last but not least...I replied your comments in the ODF file... > > > > Kind regards and many thanks for helping me there > > I'm currently in school vacation, otherwise I would have time problems too. > > Kind regards > Regina -- Olivier Hallot - Diretor EDX Informática Ltda Tel: +55-21-2178-9696 | 2178-9697 | Claro: 9 9471-1638 | Tim: 9 6556-2171 | Vivo: 9 9829-6150 http://www.edx.srv.br Cel: +55-21-9-8822-8812 </body></html>