[libreoffice-documentation] XHP cleanup
Hi, I was interested to hear yesterday that there were discussions about abandoning XHP as the file format for the help files, and use plain HTML instead. I am (so far) convinced that the actual format is not the real problem here, and that with a bit of a cleanup, XHP will be as convenient as a format as HTML would be - but with the advantage that: * we can do the changes incrementally, no big-bang necessary * there is no (or minimal) impact on the l10n * it is not blocking any later migration to "something else" * it keeps the semantics * it keeps the possibility to embed help files between themselves So let me propose some cleanups I'd like to do: * get rid of the old attributes that were used only for the helpcontent -> helpcontent2 migration (like the 'oldref' or 'l10n' attribute) * make the 'id' attribute non-mandatory, and instead check during the build for the presence of the id's that are referenced from somewhere + this needs to be done carefully not to affect l10n * get rid of xml-lang attribute, and instead mark only the strings that are _not_ supposed to be translated. * make role="paragraph" the default, so only the headings need to be marked With this, the help descriptions would change from: Heading The actual text... to Heading The actual text... which is hopefully not much more complex than HTML, and yet possible incrementally, and without affecting l10n or other parts of the existing workflow. Going further, we can later change 'paragraph' to 'p', introduce 'h2' as a shortcut for too, if we with so; but for the moment, I think there are XHP features that are worth keeping, because as a format, it gives more semantics to the text than a plain HTML would do. Any objections, please? :-) Thank you, Kendy -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
Re: [libreoffice-documentation] XHP cleanup
Hello Jan Em 16/12/2016 07:21, Jan Holesovsky escreveu: > Hi, > > I was interested to hear yesterday that there were discussions about > abandoning XHP as the file format for the help files, and use plain HTML > instead. What documenters want is a easy way to insert, edit and update help contents, as well as to add new, modern resources as multimedia and graphics in the help pages. > I am (so far) convinced that the actual format is not the real problem > here, and that with a bit of a cleanup, XHP will be as convenient as a > format as HTML would be - but with the advantage that: The format is not the problem as long as we have tools to edit the contents with the benefits as listed above. The only XHP rich editor is HelpAuthoring extension, which is still buggy and demand a long and steep learning process. By contrast, users and volunteers are much more comfortable with editors available in CMSs, forums and wikis, such as TinyMCE, CKEditor, or any other markdown editor. > > * we can do the changes incrementally, no big-bang necessary > > * there is no (or minimal) impact on the l10n > > * it is not blocking any later migration to "something else" > > * it keeps the semantics > > * it keeps the possibility to embed help files between themselves The major use we made of XHP is to display information for reading and to source information for an search index (the tags). To be displayed, XHP is transformed into HTML and presented in a specially tweaked Writer/Web module. Bookmarks are handled separately. > So let me propose some cleanups I'd like to do: > > * get rid of the old attributes that were used only for the > helpcontent -> helpcontent2 migration (like the 'oldref' or 'l10n' > attribute) OK. but cleaning up useless attributes in XHP such as oldref= and l10n= should not trigger a fuzzy state in our translation process. > > * make the 'id' attribute non-mandatory, and instead check during the > build for the presence of the id's that are referenced from somewhere > > + this needs to be done carefully not to affect l10n ID is absolutely mandatory because "filepath+filename+ID" sets the uniqueness of the string in the help system for the translation process. If we change the format XHP to format ABC, then there must be a one-to-one relation between IDs in XHP to IDs in ABC. Another constraint is that once an ID is set for a string, it must remain the same forever for that string. So, we must keep "id" and also "localize". > > * get rid of xml-lang attribute, and instead mark only the strings that > are _not_ supposed to be translated. OK > > * make role="paragraph" the default, so only the headings need to be > marked > > With this, the help descriptions would change from: > > l10n="U" oldref="13">Heading > oldref="14">The actual text... > > to > > Heading > The actual text... > > which is hopefully not much more complex than HTML, and yet possible > incrementally, and without affecting l10n or other parts of the existing > workflow. > > Going further, we can later change 'paragraph' to 'p', introduce 'h2' as > a shortcut for too, if we with so; > but for the moment, I think there are XHP features that are worth > keeping, because as a format, it gives more semantics to the text than a > plain HTML would do. Perfect. As I put above, we must keep id="...". That is not a issue at all. Note that if the format ABC is actually HTML, your example turns to Heading The actual text... and we keep the uniqueness of the ID, our translators (including me) are happy and users thrilled to use their preferred markdown javascript editor. Let me think a bit on the "localize=" attribute... > > Any objections, please? :-) I will build a wiki document comparing and commenting XHP and HTML5, for evaluation. This is not an endorsement of HTML, though. Thank you -- Olivier Hallot LIbreOffice Documentation Coordinator Comunidade LibreOffice Rio de Janeiro - Brasil - Local Time: UTC-02:00 http://tdf.io/joinus -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
[libreoffice-documentation] Getting rid of 'oldref' in the help files
Hi Cloph, all, I've recently proposed some help cleanups on the documentation@ ML, and this is the first one of them. I'm cross-posting to l10n@ and documentation@ - this change is supposed to be transparent for L10n and Documentation teams, but they should know :-) The idea is to get rid of the 'oldref' attribute in the help files; ie. change Heading to Heading The 'oldref' comes from helpcontent -> helpcontent2 migration, and the documentation says "This contains the reference number used by the old help files and is only used for migration purposes." Unfortunately, it is used in the msgctx flag in the .po files, like: #: main0503.xhp msgctxt "" "main0503.xhp\n" "hd_id3155084\n" "21\n" "help.text" msgid "Flexible Application Interface" msgstr "Snadno přizpůsobitelné uživatelské rozhraní" The "21\n" above is the oldref. As we talked on the IRC - unless there are any objections, can you please do your magic with the next translation update so that we remove these oldrefs from the helpcontent, the .po templates, and .po translations themselves? The helpcontent2 part of that is this: git grep -l 'oldref="[0-9]*"' | xargs sed -i 's/ *\http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
Re: [libreoffice-documentation] XHP cleanup
Hi Olivier, Olivier Hallot píše v Pá 16. 12. 2016 v 08:52 -0200: > > I am (so far) convinced that the actual format is not the real problem > > here, and that with a bit of a cleanup, XHP will be as convenient as a > > format as HTML would be - but with the advantage that: > > The format is not the problem as long as we have tools to edit the > contents with the benefits as listed above. The only XHP rich editor is > HelpAuthoring extension, which is still buggy and demand a long and > steep learning process. By contrast, users and volunteers are much more > comfortable with editors available in CMSs, forums and wikis, such as > TinyMCE, CKEditor, or any other markdown editor. Sure; the thing is that from my point of view it's easier to tweak such an existing tool to consume the XHP markup, than a big bang conversion to a general HTML that on one hand loses semantics (like the or tags), and on the other lets very free-form stuff going in (should people use 's and 's? Or 's and 's? Or just div's and css?). This can easily become quite messy, so having a stricter XML (like the XHP) is useful from my point of view, so that we can extend the markup where we need in a targeted way (eg. to be able to build books from that, or to add the multimedia content or so). > > * get rid of the old attributes that were used only for the > > helpcontent -> helpcontent2 migration (like the 'oldref' or 'l10n' > > attribute) > > OK. but cleaning up useless attributes in XHP such as oldref= and l10n= > should not trigger a fuzzy state in our translation process. Yes, I've already synced with Cloph on that, see the other mail :-) > > * make the 'id' attribute non-mandatory, and instead check during the > > build for the presence of the id's that are referenced from somewhere > > > > + this needs to be done carefully not to affect l10n > > ID is absolutely mandatory because "filepath+filename+ID" sets the > uniqueness of the string in the help system for the translation process. > If we change the format XHP to format ABC, then there must be a > one-to-one relation between IDs in XHP to IDs in ABC. Another constraint > is that once an ID is set for a string, it must remain the same forever > for that string. > > So, we must keep "id" and also "localize". The id is mandatory only if there are two (or more) same strings in one file, otherwise the uniqueness is given by the filepath + filename + the string itself. This can be easily mandated by a git hook that would check this (or even generate the id's in cases where necessary). > > Going further, we can later change 'paragraph' to 'p', introduce 'h2' as > > a shortcut for too, if we with so; > > but for the moment, I think there are XHP features that are worth > > keeping, because as a format, it gives more semantics to the text than a > > plain HTML would do. > Perfect. > As I put above, we must keep id="...". That is not a issue at all. Note > that if the format ABC is actually HTML, your example turns to > Heading > The actual text... > > and we keep the uniqueness of the ID, our translators (including me) are > happy and users thrilled to use their preferred markdown javascript editor. The complexity here lies in the structure, not in the markup. We need an editor that "understands" the structure, unfortunately. But again, I believe that's not a hard problem to sort out :-) In my ideal world, I'd like to see a button in the help next to the paragraph with "Improve this text", that would lead through some google (or so) sign-in to a web-based editor where the person would update the text, check a checkbox agreeing with the license, and it'd be submitted to gerrit for review. > Let me think a bit on the "localize=" attribute... > > > Any objections, please? :-) > > I will build a wiki document comparing and commenting XHP and HTML5, for > evaluation. This is not an endorsement of HTML, though. A cheat-sheet of xhp vs. html markup would be indeed useful; just to show people that xhp is not that bad if we get rid of the attributes that we don't need, but are repeated all over the place, making it look complex :-) All the best, Kendy -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
[libreoffice-documentation] Re: Getting rid of 'oldref' in the help files
> this change is supposed to be transparent for L10n and > Documentation teams, but they should know :-) It does not seem transparent for the few languages that do not use pootle (sl and sr) please do not forget those. It does also influence the help repo (of course), since the change will be a very big commit. > [Or - any objections to this change?] No objections as I think it is a good and welcome change, just a question. As we discussed in ESC (and Oliver sort of pushed) it seems the goal is to move away from .xhp to .xhtml (if I understood it correct). If decided do we then want to do that as a set of small steps or make 1 script that does it ? Please just see this as a question of how often to we want to run these conversions. have a nice weekend rgds jan I. -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
[libreoffice-documentation] Re: Getting rid of 'oldref' in the help files
Hi Jan,
Jan Iversen píše v Pá 16. 12. 2016 v 16:27 +0100:
> > this change is supposed to be transparent for L10n and
> > Documentation teams, but they should know :-)
>
> It does not seem transparent for the few languages that do not use pootle (sl
> and sr) please do not forget those.
Thanks for the reminder. I hope Cloph can do the upgrade for them some
way that fits them too, though?
> It does also influence the help repo (of course), since the change will be a
> very big commit.
>
> > [Or - any objections to this change?]
>
> No objections as I think it is a good and welcome change, just a question.
>
> As we discussed in ESC (and Oliver sort of pushed) it seems the goal
> is to move away from .xhp to .xhtml (if I understood it correct). If
> decided do we then want to do that as a set of small steps or make 1
> script that does it ?
I tried to explain on the documentation@ why a big-bang move to html is
not a good idea from many reasons in another thread; to name the most
important ones:
* big-bang "let's abandon one technology and hooray for another one"
always brings lots of regressions that are hard to fix in a timely
manner; incremental changes are easier to maintain
* html does not have markup for some of the semantics that we have (and
need) in the help files (like or to name few)
* there are many ways how to describe the same thing in html ('s and
's vs. and vs. 's with css vs. who-knows-what)
which would make the help harder to maintain, if we eg. want to reuse
the information from there to generate other representations (like
eg. books or so)
> Please just see this as a question of how often to we want to run these
> conversions.
One more may be needed if we agree that the id="..." attribute could be
done non-mandatory, because that one affects the msgctx too.
If we want to make the XHP markup look more like HTML markup (which I
don't object in general & this is up to agreement between between the
Documentation and L10n people), there might be additional conversions
needed, for things like -> etc. - but I'd like to keep
this separate from the cleanup effort / topic.
All the best,
Kendy
--
To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
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
[libreoffice-documentation] Re: Getting rid of 'oldref' in the help files
>
> it seems the goal is to move away from .xhp to .xhtml
>
> I hope you meant HTML 5, because XHTML is a dead end (and good riddance).
html does not have markup for some of the semantics that we have (and need)
> in the help files (like or to name few)
>
Both and are part of HTML 5 and there is a good chance
the other things are as well.
there are many ways how to describe the same thing in html ('s and 's
> vs. and vs. 's with css vs. who-knows-what)
CSS is the preferred way, its the same as with styles and direct formatting
in Writer.
--
To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
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
Re: [libreoffice-documentation] XHP cleanup
Hello world & Kendy, > Going further, we can later change 'paragraph' to 'p', introduce 'h2' as > a shortcut for too, if we with so; > but for the moment, I think there are XHP features that are worth > keeping, because as a format, it gives more semantics to the text than a > plain HTML would do. so while you're at it (the previous mail's been perhaps too much content for a single chunk of text & normal human attention span) ... ... can you enlighten those of use who haven't been here for so very long, what those killer features of XHP format worth keeping are? -- Katarina Behrens Softwareentwicklerin LibreOffice ––– CIB software GmbH Geschäftsstelle Hamburg Flachsland 10 22083 Hamburg ––– T +49 (40) / 28 48 42 -235 F +49 (40) / 28 48 42 -100 katarina.behr...@cib.de www.cib.de ––– Sitz: München Registergericht München, HRB 123286 Geschäftsführer: Dipl.-Ing. Ulrich Brandner -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
Re: [libreoffice-documentation] Re: Getting rid of 'oldref' in the help files
Hi, khagaroth píše v Pá 16. 12. 2016 v 17:51 +0100: > > I hope you meant HTML 5, because XHTML is a dead end (and good riddance). > > html does not have markup for some of the semantics that we have (and need) > > in the help files (like or to name few) > > > > Both and are part of HTML 5 and there is a good chance > the other things are as well. They are, but they mean a completely different thing than what they mean in XHP ;-) in XHP is more like . Similarly is more like a with some associated css. Again - I'm talking semantics; is a general thing, and has no semantics by itself, similarly . We'd lose this by converting to a plain HTML. All the best, Kendy -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
Re: [libreoffice-documentation] XHP cleanup
Hi Bubli, Katarina Behrens píše v Pá 16. 12. 2016 v 18:20 +0100: > > Going further, we can later change 'paragraph' to 'p', introduce 'h2' as > > a shortcut for too, if we with so; > > but for the moment, I think there are XHP features that are worth > > keeping, because as a format, it gives more semantics to the text than a > > plain HTML would do. > > so while you're at it (the previous mail's been perhaps too much content for > a > single chunk of text & normal human attention span) ... > > ... can you enlighten those of use who haven't been here for so very long, > what those killer features of XHP format worth keeping are? tl;dr: Semantics & focus on what it is used for. All the best, Kendy -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
Re: [libreoffice-documentation] Re: Getting rid of 'oldref' in the help files
Hi All
Em 16/12/2016 14:51, khagaroth escreveu:
>> it seems the goal is to move away from .xhp to .xhtml
>>
>> I hope you meant HTML 5, because XHTML is a dead end (and good riddance).
> html does not have markup for some of the semantics that we have (and need)
>> in the help files (like or to name few)
>>
> Both and are part of HTML 5 and there is a good chance
> the other things are as well.
>
> there are many ways how to describe the same thing in html ('s and 's
>> vs. and vs. 's with css vs. who-knows-what)
>
> CSS is the preferred way, its the same as with styles and direct formatting
> in Writer.
>
The complete XHP reference is here:
https://wiki.documentfoundation.org/HelpContentAuthoring/3
Regards
--
Olivier Hallot
LIbreOffice Documentation Coordinator
Comunidade LibreOffice
Rio de Janeiro - Brasil - Local Time: UTC-02:00
http://tdf.io/joinus
--
To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
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
[libreoffice-documentation] Re: Getting rid of 'oldref' in the help files
On 12/16/2016 05:38 PM, Jan Holesovsky wrote:
> * there are many ways how to describe the same thing in html ('s and
> 's vs. and vs. 's with css vs. who-knows-what)
> which would make the help harder to maintain, if we eg. want to reuse
> the information from there to generate other representations (like
> eg. books or so)
oh and of course HTML help content effectively requires first ditching
the current built-in Writer-based help browser, since Writer can only
handle ~HTML3 or so and if people can just write HTML5 directly they
surely don't want to be restricted to a subset with no tool to verify
they didn't get it wrong, so the pages have to be displayed by a proper
web browser.
but maybe getting rid of the Writer based online help is already part of
the goal, i don't know.
--
To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
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
[libreoffice-documentation] Re: [libreoffice-l10n] Re: Getting rid of 'oldref' in the help files
On Fri, Dec 16, 2016 at 05:51:41PM +0100, khagaroth wrote:
> > there are many ways how to describe the same thing in html ('s and 's
> > vs. and vs. 's with css vs. who-knows-what)
>
> CSS is the preferred way, its the same as with styles and direct formatting
> in Writer.
CSS is preferred for styling not semantics. But all of this is moot if
we don’t have an HTML5 help viewer anyway.
Regards,
Khaled
--
To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
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
[libreoffice-documentation] Re: [libreoffice-l10n] Re: Getting rid of 'oldref' in the help files
Hi, Jan, 2016-12-16 17:38 GMT+01:00 Jan Holesovsky : > > It does not seem transparent for the few languages that do not use > pootle (sl and sr) please do not forget those. > > Thanks for the reminder. I hope Cloph can do the upgrade for them some > way that fits them too, though? I do not mind this happening if it does not affect the l10n process. With that in mind the date/point at which it will be run must be set. Probably this will happen after 5.3.x branch? It would make sense to do it after the 5.3.0 release, when most l10n teams finish with their work and have finished translating help, and still not started translating the 5.x master. Or maybe after 5.3.1 release? The sl and sr team would probably send their po files zipped (or they would be taken from the git) and the script should be run through them and they would be entered in the git and returned to respective l10n teams. This conversion process (including the majority of l10n from Pootle) should happen in a short span (like two working days, maybe more if required by the scripts to go through all the languages and to check all converted files for consistency by some other scripts). Probably one (or a few) languages should be taken first to test this procedure/the scripts and to have better estimates of time and resources needed. Lp, m. -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
[libreoffice-documentation] Re: [libreoffice-l10n] Getting rid of 'oldref' in the help files
Hi all 2016-12-16 16:13 keltezéssel, Jan Holesovsky írta: > The idea is to get rid of the 'oldref' attribute in the help files; ie. > change > >l10n="U" oldref="13">Heading > > to > >l10n="U">Heading I did not realized oldref being part of msgctxt, so in my recent help commits removed a lot of these from the files I touched, even from otherwise untouched strings. So I probably made quite a few fuzzy strings - sorry about that. With that being said, I fully support this move, like right now :). Also if possible, please kill the l10n attribute along it. These two make my eyes bleed while editing the original xml. Regards Gabor -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 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
