Re: [libreoffice-documentation] Re: Default value ("en-US") for the "xml-lang" attribute in XHP files

[Jan Holesovsky]

Hi Tom,

Tom Davies píše v Čt 22. 12. 2016 v 10:12 +:


> Perhaps a header section, like html rather than document-headers?  Is
> that even possible in xml?  

Good point, in principle this would be possible; will keep this in mind.

Though, this is not the most important thing at the moment, as only the
extensions that have a translated help system are actually using a
non-en-US 'xml-lang'; the internal help system is not really using this
at all.

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] Default value ("en-US") for the "xml-lang" attribute in XHP files

[Jan Holesovsky]

Hi,

This is one more from the 'cleaning up XHP files' series...

At the moment, the "xml-lang" attribute in the  markup in the
XHP files is mandatory.  But I see no reason for that, it is always just
"en-US", the different locales make sense only for extensions, so I have
created this patch:

  https://gerrit.libreoffice.org/#/c/32296/

This is supposed to ensure that when there is no xml-lang in a given
attribute, it will default to en-US.

It is yet to be tested with the actually removed xml-lang from our help
files via something like:

  git grep -l '\' | xargs sed -i 's/\(]*\) 
xml-lang="en-US"/\1/g'

and updated the DTD to specify xml-lang as optional.

This will not affect the translations in any way.

Comments appreciated :-) - would like to go ahead with this sometime
after the ESC.

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] Getting rid of 'l10n' attribute in the help files

[Jan Holesovsky]

Hi,

As discussed in the other mails, 'l10n' is another attribute I'd like to
remove from the help files.

It is unused in the code, and the documentation says: "Contains the
localization status of the old help files and is only used for migration
purposes." - which has happened years and years ago with the helpcontent
-> helpcontent2 migration :-)

This should not affect the l10n process in any way.

OK to go ahead with this bulk change?

It means the following will be run:

  git grep -l '\' | xargs sed -i 's/\(]*\) 
l10n="[^"]*"/\1/g'

and a small follow-up cleanup for the paragraphs that don't have the
attribute on the same line.  Then I'd remove it from the DTD and
xmlhelp/util/compact.xsl too.

I'll wait until after the ESC call this week, for the case there are any
concerns :-)

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

[Jan Holesovsky]

Hi Olivier,

Olivier Hallot píše v So 17. 12. 2016 v 14:54 -0200:

> One thing I'd like to add for evaluation of using XML for the help
> contents in browsers is that,  in my experience:
> 
> *  XSLT (XML style sheets), XPath and XQuery  are another technologies
> to master.
> 
> * An error in a XSLT statement and one get  a blank page or a message
> with very little indications (Firefox)
> 
> * XSLT seems to be an aging technology. Is the industry betting in this
> technology for the future?
> 
> * Rendering XML+XSLT is browser-dependent and is not publicly/widely
> tested by W3C. We may be forced to test the results into a wide set of
> browsers.

Nothing stops us from rewriting the XLST transformation to plain
JavaScript, and handle the XHP files directly via JS if XSLT is blocking
us.  [And this is a reasonably self-contained, and easily testable task:
The XHP -> HTML conversion has to give the same results before and after
the rewrite for all the files.  We've got rid of XSLT in writerfilter
the same way few years ago.]

And maybe we'll eventually end up with using the plain HTML5 directly -
I definitely don't want to block evolution (even though at the moment I
see more drawbacks than gains).

But that's my main point - I want an evolution, not a revolution.  Every
time I hear about "helpcontent*3*" or "let's move to html5", I get
extremely scared, because such claims seem to suggest that we have to
throw away what we have & rewrite everything first, and miss what we
want to achieve in the first place; which from what I know is:

1) add multimedia content

2) make the editing easier

But neither 1) nor 2) have html5 (or a complete rewrite) as a
pre-requisite, for both these goals there is an incremental upgrade path
possible: Improving XHP step by step.

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

[Jan Holesovsky]

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

[Jan Holesovsky]

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

[libreoffice-documentation] Re: Getting rid of 'oldref' in the help files

[Jan Holesovsky]

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

Re: [libreoffice-documentation] XHP cleanup

[Jan Holesovsky]

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] Getting rid of 'oldref' in the help files

[Jan Holesovsky]

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/ 

[libreoffice-documentation] XHP cleanup

[Jan Holesovsky]

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] 2016 budget proposals

[Jan Holesovsky]

Hi Sophie,

Sophie píše v Pá 26. 02. 2016 v 13:51 +0100:

> > Olivier is currently working on a webservice that is able to show the
> > help online [and hopefully in a better quality than the current
> > wikihelp].
> 
> Thanks to Olivier for this great work, I tested it yesterday and it's
> already a nice move. Just for my understanding, I thought it was to be
> able to replace the current embedded browser LibreOffice is providing.
> So that mean that the help files could be displayed either locally and
> on a webservice?

That's the hope, yes.

> And the wiki will be abandoned in that case?

No point in maintaining 2 services doing the same work; so once the
pages generated directly from .xhp's are better than those from
wikihelp, I can imagine the switch & slowly abandoning wikihelp
("freeze" it and make available only for old versions, or so).

> > Technically, it would still work on top of the .xhp files; it turns out
> > that we can clean up the format a bit to make it more readable, and
> > changing all the tools and workflows is too much work.
> 
> I forgot where do we stand with the extended tooltips, is there still a
> technical issue to extract them and what remains is the l10n problem?

With working directly on .xhp's, the extended tooltips are not a blocker
any more, can be extracted or not, neither of these possibilities is a
problem.

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] New writer

[Jan Holesovsky]

Hi Andrew,

Olivier Hallot píše v Čt 25. 02. 2016 v 12:39 -0300:
> Welcome Andrew
> 
> Skilled writers are a jewel we care.
> 
> Please follow the advise of the landing page of ODFAuthors.org to get
> your account:
> 
> "Please write to webmas...@odfauthors.org and request an account. (We
> had to stop self-registration because of too many spam accounts.) But
> first! Please subscribe to the odfauthors-discuss mailing list and
> introduce yourself."
> 
> Looking forward to see you in our documentation community.

Welcome indeed! :-)

What are you most interested in, please - writing new documentation?  Or
improving the existing one?  In which area?  [Writer / Calc / Impress /
Base / anything else?]

We are currently trying to improve the LibreOffice help system; many new
LibreOffice features are not documented at all, and we should fix that.

Is that something you'd be interested in helping with? - we will be
happy to bootstrap you there.

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] Help-files: Large-scale 'cosmetic' changes

[Jan Holesovsky]

Hi Tom,

Tom Davies píše v St 16. 12. 2015 v 19:15 +:

> It is about the Help Files.  The Documentation Team may be able to
> make some much-needed changes to the help-files.  However, it is to
> solve a problem that only exists in English.  For all other languages
> it is, beyond doubt, already corrected purely through the translation
> process.
> 
> Is there a system or tool that allows such sweeping changes without
> marking completed translations as incomplete?
> 
> I think there was some discussion about developing such a tool but i
> imagine it would be extremely difficult to make something like that.
> So i would be surprised if there is anything yet.

I don't think it is terribly difficult to create such a tool, the
problem is running it - it has to by done by an admin with the access to
Pootle, so doing it string by string for each such much needed (but for
other languages cosmetic) change would be rather sub-optimal.

But - what about to introduce an 'en_US' translation in the Pootle,
where native speakers could improve the wording without changing the
meaning?  Then once per the release cycle, these could be copied back in
a way that it marks no translations fuzzy.

[Again - this does not cover those who download the .po files from
Pootle, and then upload back; but hopefully with a proper communication,
giving them enough time to upload their work before such a change, this
could be less of a problem too?]

Does that work?

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] Use of "allow to" in documentation

[Jan Holesovsky]

Hi Peter,

Peter Toye píše v St 02. 12. 2015 v 16:13 +:

> OK, when I have time I'll fix the wiki, That's the easy bit.

Cool, thanks! :-)

> For the help files, I already have a Git system on my PC (used with
> Visual Studio Express), but don't know Gerrit at all. I'll read
> through the documentation on how Git is used for the help files, but I
> think I'll need help on Gerrit. It won't be for a few days.

I see.  gerrit is (just) a review system; in other words, a system that
allows everybody to have write access - you can commit and push your
changes (to gerrit), where somebody with the appropriate rights will
read your change, and either comment on that (so that you know what to
fix), or will merge it to the main git.

You need to do a bit of a setup:

https://wiki.documentfoundation.org/Development/gerrit/setup

but then for your work, you'll push very similarly as with the normal
git.

>  I don't have an IRC client (or does WIndows 7 have one built-in -
> I've not found it?) so that will be the first thing. What timezone are
> you in - your name implies the Central European time zone - UTC+1, so
> it shouldn't be too difficult to find a time that we're both awake.

Better if you have an IRC client, but if not, you can join via web too:

https://webchat.freenode.net/

Join the #libreoffice-dev channel, I'm sure you'll find many people who
will be able to help you with the gerrit setup, if I'm not around or not
responding from some reason (I'm "kendy" there).

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] Use of "allow to" in documentation

[Jan Holesovsky]

Hi Peter,

ptoye píše v Po 30. 11. 2015 v 04:28 -0700:

> There's an example below taken from
> https://wiki.documentfoundation.org/HelpContent#Make_Images_Appear which
> shows the problem:  three of these paras use "allows to", three don't, but I
> think they all have the same meaning!

This is very easy to fix.  wiki.documentfoundation.org is editable by
anyone who registers; so if you can register & log in, then you'll see a
small [edit] link next to the item that's wrong.

When you press it, it will lead you directly to the text - please just
correct it to use the correct English, check the draft, and publish it,
no approval by anybody is needed there.

Having said that; what is worse, we have these mistakes in the help
itself too.  IIRC you told that it is hard for you to set up the git
repository - can we eg. meet on IRC to go through the process together,
so that you can make the improvements there too?

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: [libreoffice-l10n] Possible help files rename?

[Jan Holesovsky]

Hi Martin,

Martin Srebotnjak píše v Út 24. 11. 2015 v 21:57 +0100:

> I am not sure we are talking about the same thing or that I understand
> this correctly.
> 
> They change the names of the help files (i.e. calc/01.po is now
> calcsfirsthelpfilewithhelpaboutfunctions.po). For the migration
> process they become new po files.

Nope, did not intend to change the directories, so I was happy to hear
that the .po files are named by the directories.

So as a result, calc/01.po will still stay calc/01.po; only the
filenames inside would change - eg. in:

#. ZxQeC
#: main.xhp
msgctxt ""
"main.xhp\n"
"tit\n"
"help.text"
msgid "Welcome to the $[officename] Calc Help"
msgstr "Vítejte v nápovědě k $[officename] Calc"

only the 'main.xhp' would change to 
'-Welcome-to-the-officename-Calc-Help.xhp' resulting in

#. ZxQeC
#: -Welcome-to-the-officename-Calc-Help.xhp
msgctxt ""
"-Welcome-to-the-officename-Calc-Help.xhp\n"
"tit\n"
"help.text"
msgid "Welcome to the $[officename] Calc Help"
msgstr "Vítejte v nápovědě k $[officename] Calc"

Sorry for not being precise in my question previously, but first I
needed to understand how exactly the .xhp's map to the .po files :-)

Does this work / is this change possible without much hassle?

Thank you again,
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: [libreoffice-l10n] Possible help files rename?

[Jan Holesovsky]

Hi Sophie,

Sophie píše v St 25. 11. 2015 v 11:52 +0100:

> Why do we want to change if the main_transform.xsl file is working now
> correctly and allow an easy search? I agree that the file name remains
> not easy to understand, but if a tool solve that, where is the issue
> then?

From my point of view, it is always good to fix root cause, then to try
to pile workaround on top of each other to achieve something that would
be possible by fixing the initial problem in the first place.

Additional file means additional complexity, and additional thing to
explain to the newcomers - so that's why I am interested in fixing this
by the rename.

But again - for the moment I'm only researching what are the
consequences & if this is acceptable by the l10n community :-)

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] Possible help files rename?

[Jan Holesovsky]

Hi Regina, all,

Regina Henschel píše v St 18. 11. 2015 v 21:32 +0100:

> most of the file names are build of numbers and it 
> is hard to identify the relevant file.

That's indeed true :-)

I wonder - would a large scale rename to something more readable (like
eg. filename constructed from the  tag) be more appreciated by
people editing help?

L10n people - any blockers from the tooling point of view that hinder
that, please?  Would it mean that the .po files have to be renamed too,
and if yes, it is possible to do that somehow automatically?

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] Introduction

[Jan Holesovsky]

Hi Ava,

Ava Jarvis píše v Ne 08. 11. 2015 v 22:21 -0800:

> My software engineering background gives me the capability of additionally
> taking on tasks for writing documentation geared towards developers. In
> addition I have the writing and mentoring skills to write end-user
> documentation, tutorials, and guides. (I used to be a head TA for UIUC's
> Programming Languages and Compilers class, though that was many moons ago
> indeed.)

Welcome to LibreOffice :-) - it is great to have you around.

> Can someone open an account on the ODFAuthors site for me?

I don't have the rights to give ODFAuthors access to you, but can offer
something else that might interest you too - that connects the
development and documentation together.

We are working on improving the built-in help; both the content and the
tools around that.  To be able to work effectively on the help files, we
are using an extension, for details see:

https://wiki.documentfoundation.org/HelpContent

For editing the help files, you don't need any account setup first, you
can directly start improving them, and then push your changes via gerrit
(our review system).  Hopefully the wiki page is helpful, but if you
have questions, please do ask here.

You can also help us improving the HelpAuthoring extension, there is a
tracker bug here:

https://bugs.documentfoundation.org/show_bug.cgi?id=93580

Please let us know should you have any further questions.  I am looking
forward to your contributions!

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] HelpAuthoring-3.1.4.oxt released

[Jan Holesovsky]

Hi,

I've released a new version of the HelpAuthoring extension.  It is
available here:

  http://dev-www.libreoffice.org/helpauthoring/

Please upgrade to this version, it is recommended for real use - please
help us creating the help pages!  It needs LibreOffice 4.4 or later.

The following has been improved in the version 3.1.4:

+ tdf#94201: No 'localize' on the 'switch' element (Regina)
+ tdf#94201 Dont import blank visibility attribute of  tag 
(Regina)
+ tdf#93981 Attribute localize=(false|true) is deleted (Regina)
+ correct path help/ to helpcontent2 and clarify (Eike)
+ make sure to select the full title line in wizard (Jay)
+ tdf#95509 Retain image size on save (Jay)

If you find bugs, please check the bugzilla if it is already reported,
and if not, report it, and set it as blocking the tracker bug:

  https://bugs.documentfoundation.org/show_bug.cgi?id=93580

Or of course try to fix it, it is not that hard :-)  How to hack it is
described here:

  
http://cgit.freedesktop.org/libreoffice/contrib/dev-tools/tree/helpauthoring/README

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] Are id attributes needed on paragraphs and headings in .xhp help files?

[Jan Holesovsky]

Hi Regina,

Regina Henschel píše v St 07. 10. 2015 v 15:33 +0200:

> the doctype definition xmlhelp.dtd makes the id attribute of type 
> REQUIRED in all cases. It is needed surely for sections and variables, 
> because they are embedded elsewhere and need to be referenced.
> 
> But is the id attribute needed for headings and paragraphs too? There 
> exists already some files having paragraphs without an id attribute, and 
> the files in the delivered .jar archives have stripped the attribute 
> too. But I do not know whether processes exists, that need it. What 
> about translation, or transformation to the Wikihelp, or the help 
> compiler itself, or while generating the .jar files?
> 
> If the id attribute is not needed, then the authoring tools can do 
> without generating id values.

Sorry for the late answer.  From what I know, the paragraph ID's are not
necessary for wikihelp, and I doubt they are necessary for the help
compiler.

Let me add the l10n team to see if they are necessary for the
translations...  Are they?

If not - then I'd remove them from the tooling, dtd, and from the help
repository too, to reduce the noise there :-)

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

[libreoffice-documentation] HelpAuthoring-3.1.3.oxt released

[Jan Holesovsky]

Hi,

I've released a new version of the HelpAuthoring extension.  It is
available here:

  http://dev-www.libreoffice.org/helpauthoring/

Please upgrade to this version, it is recommended for real use - please
help us creating the help pages!  It needs LibreOffice 4.4 or later.

The following has been improved in the version 3.1.3:

+ file type detection for .xhp files (Maxim)
+ show the menu in the Start Center too (Maxim)
+ don't turn fields into expressions (Regina)
+ improve the creation of unique paragraph ID (Jay)
+ improve inline 'switch' functions + add to toolbar (Jay)
+ improve git comparison (Jay)
+ paragraph ID fields should not be hidden (Regina)

If you find bugs, please check the bugzilla if it is already reported,
and if not, report it, and set it as blocking the tracker bug:

  https://bugs.documentfoundation.org/show_bug.cgi?id=93580

Or of course try to fix it, it is not that hard.  How to hack it is
described here:

  
http://cgit.freedesktop.org/libreoffice/contrib/dev-tools/tree/helpauthoring/README

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] HelpAuthoring-3.1.2.oxt released

[Jan Holesovsky]

Hi,

I've released a new version of the HelpAuthoring extension.  It is
available here:

  http://dev-www.libreoffice.org/helpauthoring/

Please upgrade to this version, it is recommended for real use - please
help us creating the help pages!  It needs LibreOffice 4.4 or later.

Jay is the hero of this release, he has fixed a tremendous amount of
bugs, and implemented many features - thank you!  Follows a shortened
list:

* Usability improvements

+ Much improved menu, and added entries for many features (Jay)
+ Toolbar for easy access of the most needed features (Jay)
+ Wizard for creating a new page (Jay)
+ Suppress unnecessary dialogs (Jay)
+ Command to compare changes in git (Jay)

+ Insert product name and version variables (Jay)
+ Insert switch and switchinline tags (Jay)

+ Ability to reload the help (Jay)
+ Open embedded or linked help (Jay)
+ Use the last used dir when opening file (Jay)

* Bugfixes and file format improvements

+ Make the diffs between original & edited version smaller by
  reordering some attributes (Jay)
+ Don't clear help topic id and indexer, don't set indexer when
  creating a new page (Jay)
+ Various fixes to functions so that they preform better (Jay)

+ Improve the template (Jay)

If you find bugs, please check the bugzilla if it is already reported,
and if not, report it, and set it as blocking the tracker bug:

  https://bugs.documentfoundation.org/show_bug.cgi?id=93580

Or of course try to fix it, it is not that hard.  How to hack it is
described here:

  
http://cgit.freedesktop.org/libreoffice/contrib/dev-tools/tree/helpauthoring/README

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] Help file tag questions

[Jan Holesovsky]

Hi Jay,

Yousuf 'Jay' Philips píše v Pá 11. 09. 2015 v 02:49 +0400:

> > The list of all attributes and tags that are stripped from the content
> > when packing the help is here:
> >
> > xmlhelp/util/compact.xsl
> 
> Couldn't find this file.

Sorry, it's in the 'core' repo:

http://cgit.freedesktop.org/libreoffice/core/tree/xmlhelp/util/compact.xsl

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] HelpAuthoring-3.1.1.oxt released

[Jan Holesovsky]

Hi,

I've released a new version of the HelpAuthoring extension.  It is
available here:

  http://dev-www.libreoffice.org/helpauthoring/

Please upgrade to this version, it has the following fixes:

* Keeps the leading '/' in  (thanks to Regina)
* Has better organized menu (thanks to Jay)
* Forces the user to set the Document Root (Kendy)

This version needs LibreOffice 4.4 or later.

If you find further bugs, please check the bugzilla if it is already
reported, and if not, report it, and set it as blocking the tracker bug:

  https://bugs.documentfoundation.org/show_bug.cgi?id=93580

Thank you for helping authoring the help! :-)

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: Ease maintenance of build-in help

[Jan Holesovsky]

Hi Regina,

Jan Holesovsky píše v St 12. 08. 2015 v 07:44 +0200:

  Authors of help texts are allowed to start in ODF to discuss and 
  finalize the content and appearance of the intended help texts. There 
  should be a place in the repository to store such files. This way 
  authors did not need deep knowledge of the technical structure of 
  helpcontent2. The person who integrates the help texts into the build-in 
  help need not be the content author.
 
 That's perfectly possible.  Let's just use Flat ODF (.fodt) as the
 fileformat, and store the file next to the appropriate .xhp in the help
 repository.

I forgot to mention - it is easily possible to convert such .fodt's
to .xhp offline, without using LibreOffice.  You need only xsltproc and
the filter from dev-tools:

[git clone git://anongit.freedesktop.org/libreoffice/contrib/dev-tools]

cd dev-tools
xsltproc helpauthoring/filter/soffice2xmlhelp.xsl helpfile.fodt  helpfile.xhp

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: Ease maintenance of build-in help

[Jan Holesovsky]

Hi Regina,

Regina Henschel píše v Ne 02. 08. 2015 v 19:06 +0200:

 I have started a new thread so that the problem is not hidden inside 
 other threads or in private mails.
 
 First, is there consensus, that the current build-in help will be retained?

Thank you for your thoughts on this topic - and sorry for my late reply.
In the ideal world, I'd like the help be handled like this:

* wikihelp is the authoritative source, with appropriate approval system
  etc. [easy for casual contributors to fix stuff in the help, but safe
   easy to keep the standards]

* existing translations converted so that there is no additional work
  for the translators when converting to wikihelp (once)

* built-in help is generated from the wikihelp + translatios, and shown
  in the browser (JavaScript used for the indexing  search), instead of
  the home-grown help system

Currently we have the following pieces of the puzzle:

* ability to convert .xhp's - wiki format
* ability to convert wiki format - html

The indexing IIRC is not retained at the moment, and also the JavaScript
indexing is not implemented; so the switch is impossible in the current
state.  I am unable to work on this, but would be extremely happy to
mentor anybody who would be willing to help.

For the wikihelp itself, it might be possible to use the Mozilla's
Kitsune (the engine behind support.mozilla.org):

https://github.com/mozilla/kitsune

but that needs checking - whether it is better for our purposes than the
'normal' mediawiki or not.

 If not, then the following ideas are useless and starting would be waste 
 of time. In such case, please stop me immediately.

As you can see - the ideal world vision is long-term :-)  So let's not
allow perfect be enemy of the good, and improve the current workflow in
the meantime.

 I collect here some ideas from some threads and mails:
 
 A
 Authors of help texts are allowed to start in ODF to discuss and 
 finalize the content and appearance of the intended help texts. There 
 should be a place in the repository to store such files. This way 
 authors did not need deep knowledge of the technical structure of 
 helpcontent2. The person who integrates the help texts into the build-in 
 help need not be the content author.

That's perfectly possible.  Let's just use Flat ODF (.fodt) as the
fileformat, and store the file next to the appropriate .xhp in the help
repository.

It would be still good to use the helpauthoring.oxt when generating the
odt too, to use the appropriate fields, and to use the same template as
the start.

 B
 Improve the extension HelpAuthoring and fix its bugs. The extension 
 might be principally not suitable to generate the final version of a 
 help file, but it is useful as start, because it sets a lot of the 
 needed XML-elements and attributes automatically. The result might still 
 needs additions and corrections, but that is less work, than writing all 
 from scratch. Even if someone do not know all details about the help, he 
 can start and deliver a file, which other then can improve and integrate.

Definitely.  The xslt filter that is responsible for converting fodt -
xhp is actually trivial, I'm happy to fix bugs there when you send me
the original .(f)odt, resulting .xhp (generated by the 'broken'
helpauthoring.oxt), and the fixed .xhp (that is modified how it is
supposed to look like).

 C
 Provide a development section about the build-in help to the Wiki. It 
 should not only contain a tutorial about help authoring but in addition 
 a description how the current help works at all from a developer view, 
 and how it is actually structured.

I attempted that here:

https://wiki.documentfoundation.org/Documentation/Help

I'd like this page to become a kind of do this and that, and you'll
have a minimal useful help for your new feature for the developers -
ie. assuming that the person knows git etc.  Improvements most
appreciated!

 We can start with the document OOo2HelpAuthoring.pdf. The content has 
 to be revised and adapted and extended. For example the .mk files are 
 different than described in that document and the document describes the 
 possibilities of the help format, but not all details of the actual 
 realization.

There is also a more verbose

https://wiki.documentfoundation.org/HelpContent

that I think could be this stripped down OOo2HelpAuthoring.pdf.  We
should probably move it to Documentation/HelpContent so that it is in
the right section of the wiki (?)

 Having it in the Wiki keeps such knowledge available, when a help expert 
 leaves the community. It can be adapted to future developments. Experts 
 of different areas can better work together to collect help knowledge in 
 one place, for example experts for Help to Wiki and experts for 
 translating help.
 
 D
 It would ease work, when there would be a tool, that shows a .xhp file 
 the same way as it it shown in the help viewer, so that it is not needed 
 to build helpcontent2 every time when you test some 

[libreoffice-documentation] Re: Ease maintenance of build-in help

[Jan Holesovsky]

Hi Thorsten,

Thorsten Behrens píše v Út 04. 08. 2015 v 17:06 +0200:

  First, is there consensus, that the current build-in help will be retained?
  
 I think - the plan to go all-in for wiki-based help is on hold, until
 someone (Kendy?) has cycles to push it further.

Added some details in the other mail :-)

  A
  Authors of help texts are allowed to start in ODF to discuss and finalize
  the content and appearance of the intended help texts. There should be a
  place in the repository to store such files. This way authors did not need
  deep knowledge of the technical structure of helpcontent2. The person who
  integrates the help texts into the build-in help need not be the content
  author.
  
 Makes sense. For storing those WIP versions in the repo, I'm not sure
 that gives us much. Perhaps collaboration via owncloud or wiki works
 better there?

I'm not much a friend of having stuff on many places, so I'd prefer just
a .fodt next to the appropriate .xhp, and be done with that.  But of
course - what fits the documentation authors best...

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] Help Authoring Extension

[Jan Holesovsky]

Hi,

I've spent some time today fixing the HelpAuthoring extension, and
together with the Regina's fix (thank you, Regina!), I think it got to a
usable state :-)

  https://wiki.documentfoundation.org/Documentation/Help

describes where to get it, and the basic usage.  More detailed user
manual can be found here:

  https://wiki.documentfoundation.org/HelpContent

The .xhp's generated by the extension are now nicely formatted, which
means that when you save a .xhp in the help repository, it will likely
be a big diff the first time (due to the changed formatting - strings
should be preserved); but from then on, the changes should be tiny, as
the format will be much better defined.

Also the editing directly in LibreOffice seems to be neat  usable.
There might be rough edges still - but I hope no blocker any more.

In other words - *no excuses* for not writing help any more ;-)

Please do use it, and if you experience trouble, either fix it yourself:

  
http://cgit.freedesktop.org/libreoffice/contrib/dev-tools/tree/helpauthoring/README

or let me know - the xslt that implements the export filter is trivial.

Would be good to start thinking of a workflow between the developers and
the documentation team - I imagine developers could stub help for things
they are developing, and the documentation team members would then
finalize and de-hackerize that, but ideas how to grow the community of
help authors much appreciated.

[BTW - if you are wondering about the editable wikihelp: no, I'm not
abandoning the idea; but that is a long-term quest, and the help needs
improving _now_.]

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] MS Office - LibreOffice migration guide

[Jan Holesovsky]

Hi all,

I was wondering - please, do you know of a recent MSO - LO migration
guide?

There seems to be an old migration guide that was written in the
OpenOffice.org 2 times, but I was unable to find anything more recent.
Do you know if there is something?  Are the sources of the old one
available somewhere in case somebody wanted to update it to LibreOffice?

Thank you a lot,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@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: How does a documentation contributor work on help.libreoffice.org?

[Jan Holesovsky]

Hi David, Kohei,

On 2011-08-08 at 09:30 -0400, Kohei Yoshida wrote:

 You should CC kendy when you need to ask him specifically.

Yes, that works best - Kohei, thanks for CCing! :-)

  I'll be needing to work on help.libreoffice.org to contribute to the
  squashing of a few docs-related bugs. I already have my user account
  with the needed permissions, and can log in OK.
  
  So I just jump in and edit?

Unfortunately, the wikihelp is still not the ultimate source of the
help, so the right way how to change help now is to edit directly
the .xhp files.  You need to clone the 'help' repository, and edit
there:

git clone http://cgit.freedesktop.org/libreoffice/help

Ideally using a normal text editor (Vim, Emacs, ...), and committing to
git.  Unfortunately this is not as easy as editing the wiki pages;
that's why all this wikihelp project has started :-)  Currently there is
a Google Summer of Code student working on this (with me mentoring).

Unfortunately the switch cannot happen before the wikihelp - native
help convertor is finished, and works really well :-(

  What happens if I want to create new pages?
  
  What happens if I want to re-order page structures?
  
  What else do I need to do to make sure that the new or edited info
  integrates OK with the help?

This document describes how to work with .xhp files:

http://documentation.openoffice.org/online_help/OOo2HelpAuthoring.pdf

But unfortunately it is not too convenient; and I have no idea how much
has that changed since it was written (but the basic concepts are still
valid).
 
  Are there any other things I need to be aware of in order not to mess
  something up?

Might be best to appear on the #libreoffice-dev mailing list, we'll help
you there with git to get the most recent help, and with the .xhp files
editing :-)

Thank you a lot,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@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] online registration menu element - 404

[Jan Holesovsky]

Hi Kami,

On 2010-12-24 at 23:54 +0100, Kálmán „KAMI” Szalai wrote:

 If someone enables online registration menu element, and click on it
 gets a pege with 404 error. The address is:
 http://survey.libreoffice.org/user/index.php
 please put a redirector here, or we should change the link in LibO.

Somebody has fixed that (thank you!), now it redirects to
www.libreoffice.org.

But how exactly do you mean it with enabling the online registration
menu - by an user action, or during the build?  I'd say the best thing
would be to get rid of that completely, and remove all the related
code...

Regards,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org
List archive: http://listarchives.libreoffice.org/www/documentation/
*** All posts to this list are publicly archived for eternity ***

[libreoffice-documentation] Re: [Libreoffice] online registration menu element - 404

[Jan Holesovsky]

Hi Bernhard,

On 2010-12-30 at 02:16 +0100, Bernhard Dippold wrote:

 But there already has been a thread on the marketing list (IIRC) asking 
 for an improved user feedback in future - probably quite helpful for 
 marketing and UX. If such a feature can be based on the present code, I 
 don't know if it is reasonable to remove it completely.

Redirecting to a webpage is a few lines of code, nothing that cannot be
revived quickly should the need be :-)

Regards,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org
List archive: http://listarchives.libreoffice.org/www/documentation/
*** All posts to this list are publicly archived for eternity ***

[libreoffice-documentation] Better wording for 'Update links' question

[Jan Holesovsky]

Hi,

https://bugs.freedesktop.org/show_bug.cgi?id=32548

The bug says: when I open a certain .odp document, I get a pop-up
question asking Update all links? Yes/No

Anybody who knows this functionality, can you please provide a better
wording? ;-)  Just post it here, I'll integrate it.

Thank you a lot,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

[libreoffice-documentation] Re: [libreoffice-l10n] Re: Embedded parts and wikihelp/HC2

[Jan Holesovsky]

Hi Martin,

On 2010-12-16 at 19:08 +0100, Martin Srebotnjak wrote:

  We can easily show a suggestion to download a localized version of the
  help on each and every page, if the language is not en_US.  With your
  help (the l10n team), this can be even shown in the native language of
  the user, with a direct link to the download location.  How does that
  sound?
 
 While that would also be nice to have, I think it is mandatory to explain
 that during installation. And at the end of installation it would be nice to
 have a link to download the language pack. At least for Windows and OSX,
 that have a GUI installer.

I've just seen the test installation of the future LibreOffice site; I
think it very much fulfills what you are proposing.  It is not at the
end of the installation, but at the time you are downloading
LibreOffice:

http://test.libreoffice.org/download/

If you choose Linux version, you can choose the language version you
need, as an additional download.  I suppose the same will be implemented
with the Windows version after the RC2 that will have the langpacks.

I hope this resolves even this concern :-)

Regards,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

[libreoffice-documentation] Re: [libreoffice-l10n] Re: Embedded parts and wikihelp/HC2

[Jan Holesovsky]

Hi Sophie, all,

On 2010-12-16 at 18:07 +0300, Sophie Gautier wrote:

  How does that sound?  If this plan is acceptable for all, I can go
  ahead, and start working on this :-)
 
 For me it is, and I think that every body will the happy with your 
 proposal. Thanks a lot :-)

I have just updated the wiki accordingly:

http://wiki.documentfoundation.org/Development/Wikihelp

Please double-check, I hope I did not forget anything :-)

Regards,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

[libreoffice-documentation] Re: [Libreoffice] LibreOffice WikiHelp

[Jan Holesovsky]

Hi Muthu,

On 2010-12-08 at 19:40 +0530, Muthu Subramanian K wrote:

 I guess we should tie the 'help-welcome' (the page that opens when the
 user clicks Help-Help from menu) pages to the wiki/Main_Page or
 probably create a LibreOffice welcome help page (to point to the Writer,
 Calc, and other applications help-start pages)...
 I too felt it odd for it not to have it. Just my thought...

We have these, eg. when you hit F1 in a freshly opened Writer, you get
to:

http://help.libreoffice.org/Swriter/start

Actually - if anyone volunteers to improve the Main_Page (eg. collect
links to swriter/start, scalc/start, ...), I'll be happy to create the
account for him to do that; or I can cut and paste any improvements sent
to this thread directly as an wiki update.

Though - as I already explained, first it is necessary to fine-tune the
conversion tooling, the things like the exact wording of the Main_Page
can be fixed as soon as I feel confident with the result of the
conversion so that I can open it for everyone to edit.

Regards,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

[libreoffice-documentation] Re: LibreOffice WikiHelp

[Jan Holesovsky]

Hi all,

On 2010-12-06 at 17:04 +0100, Jan Holesovsky wrote:

 Either way, the good news is that I am currently uploading the files,
 and I'll make the site online as soon as it finishes, and I do few
 trivial checks; it should be later today (ETA 5 more hours, I am
 populating the database through the Mediawiki API, not directly).  So
 far I am uploading only the English version.
 
 It will be read-only until RC2, so that it is easy to report bugs
 against the tooling that converts the help from the format that is used
 in the source code.  After RC2, I plan to open it for your edits 
 improvements :-)

http://help.libreoffice.org is now up and running.  As explained above,
it is not open for public editing yet.  There are few known bugs already
filed in the bugzilla, should you find more, please report them too,
with 'wikihelp: ' in the subject, and assign them directly to me.

The already reported bugs are:

https://bugs.freedesktop.org/show_bug.cgi?id=32173
https://bugs.freedesktop.org/show_bug.cgi?id=32174

You can either test the wikihelp directly from LibreOffice RC1, by
issuing help on various parts of the suite (if you find something that
leads to non-existing page, please report it too), or just from your
browser, using 'Random page' in the left hand menu, and visually
scanning it :-)

I'll improve the tooling according to your findings, and upload the
improved versions of the pages.

Thank you a lot,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

[libreoffice-documentation] LibreOffice WikiHelp

[Jan Holesovsky]

Hi,

I am sorry - I promised the LibO online help (WikiHelp) already the last
week, but it haven't happened; it needed more work than anticipated :-(

Either way, the good news is that I am currently uploading the files,
and I'll make the site online as soon as it finishes, and I do few
trivial checks; it should be later today (ETA 5 more hours, I am
populating the database through the Mediawiki API, not directly).  So
far I am uploading only the English version.

It will be read-only until RC2, so that it is easy to report bugs
against the tooling that converts the help from the format that is used
in the source code.  After RC2, I plan to open it for your edits 
improvements :-)

Regards,
Kendy


-- 
Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***