LibO Documentation

Hello all,

# I don't keep myself up to date with this list so please excuse for my questions.

Now we have LibO documentation in two forms

1) Wiki: http://help.libreoffice.org/Main_Page
2) Offline install

My questions are

a) Which one is master
b) Which one should I work on
     # I am from Vietnamese l10n team

Regards,

Nguyen Vu Hung

Hi :slight_smile:
Neither. Alfresco is the place. This is an old guide that needs updating ...
http://wiki.documentfoundation.org/Documentation/Development#First_steps_with_the_Documentation_team

Hopefully someone will set you up with an Alfresco account soon.
Regards from
Tom :slight_smile:

Tom, I think he's asking about the Help, which as far as I know is not on Alfresco.

And I'm not sure who is in charge of the Help, but I don't think it's us.

Jean

Hi,

And I'm not sure who is in charge of the Help, but I don't think it's us.

Erm, actually, the devs do seem to think it is us, which I find fairly
logical. That's why they keep CC'ing me all bugs involving the
built-in help.

I guess we could currently consider me to be first custodian of
built-in help issues, although *anyone* is welcome to work on them.
I'll be happy to foster anyone wanting to tool up for the job.

I'll create an Alfresco account for Nguyen and mail him the detals, in
case it's useful for him.

Hi,

Now we have LibO documentation in two forms

1) Wiki: http://help.libreoffice.org/Main_Page
2) Offline install

My questions are

a) Which one is master
b) Which one should I work on
   # I am from Vietnamese l10n team

In case you decide you want to use Afresco as platfor for developing
Vietnamese documenation, I can create a Vietnamese work space and
group.

Please just let me know if you want that.

Right now, I've added you to the English group.

Ngày 11/11/08 1:14, David Nelson vie^'t:

In case you decide you want to use Afresco as platfor for developing
Vietnamese documenation,

Yes, of course I do :slight_smile:

I can create a Vietnamese work space and
group.

Please create one and point the them.

Please just let me know if you want that.

Right now, I've added you to the English group.

By the way, now I know what i18n teams are not parts of Documentation team.

You (Documentation team) creates docs, we (i18n teams) translate.

After receiving Alfresco credentials, I will go back to where I should be - i18n :slight_smile:

Cheers,

Nguyen Vu Hung

Ah, OK. That brings us back to the original question: where are the Help source files? And related questions about how/where/when to write/edit the Help. Is this work all tracked through the issue/bug system? Devs say "here is a new or changed function or dialog box which needs Help written/revised?"

I'd like to add something, even if (at this point) brief and general, to the Documentation Contributors Guide. I know little or nothing about it, but I do recall discussion at several times over the past year. And i know that, because the Help is shipped as part of the product, it's handled differently from the user guides and other docs we deal with here.

--Jean

Hi Vu Hung,

I can create a Vietnamese work space and
group.

Please create one and point the them.

OK. Please can you provide me with the translation into Vietnamese of
the word "Vietnamese" plus the description "Content in Vietnamese
language"?

Hi Jean,

Ah, OK. That brings us back to the original question: where are the Help source files? And related questions about how/where/when to write/edit the Help. Is this work all tracked through the issue/bug system? Devs say "here is a new or changed function or dialog box which needs Help written/revised?"

Well, I guess I could add content to the contributor docs about this.
Rainer Bielefeld popped up on this list a few months back asking how
he should in form us of new bugs/work requests. He's now forwarding
them to me, and I forward them to the list here, and bookmark them in
my mail for attention.

IIRC, the idea was to CC someone rather than the docs ML because it
might get a bit spammy with the interaction that shoots back and forth
about some bugs. Does this seem sensible?

I think this is a good approach at this time. Further thought: If we
don't yet have a wiki page where someone (not necessarily you) lists
these issues as they come in (so we can track them), then we should
set one up. People can then see what's needed and put their name down
to work on it. Forwarding initial contact to list is important, but a
tracking page on wiki is also needed.

My main questions are to do with how and where we write/edit help:

* In the Help files themselves? (If so, where?)

* By attaching a file (what format?) to the issue, so someone else can
incorporate it in the help?

And what to do if someone on the Docs team finds Help that needs
copyediting, enhancement, etc? Open an issue about it, attaching an
edited/revised version? Edit the Help file directly?

Depending on the length and detail of the answer, this might become
part of an existing chapter of the Contributors Guide, or it could be
a chapter on its own. IMO it's very important to distinguish between
how to work on the Help vs how to work on the user guides.

--Jean

Hi Jean,

I think this is a good approach at this time. Further thought: If we
don't yet have a wiki page where someone (not necessarily you) lists
these issues as they come in (so we can track them), then we should
set one up. People can then see what's needed and put their name down
to work on it. Forwarding initial contact to list is important, but a
tracking page on wiki is also needed.

Yes, it would be a good idea to keep track of these bugs, otherwise
they just subside into the depths of the ML's message history. I'll
write up what I've got already bookmarked in my mail.

My main questions are to do with how and where we write/edit help:

* In the Help files themselves? (If so, where?)

There has been a project for a wiki-based help in the pipeline for a
few months but, for the moment, the work still involves checking out
the codebase from Git and editing files within it.

* By attaching a file (what format?) to the issue, so someone else can
incorporate it in the help?

Hmmmmm, well, to obtain the content to edit, someone would have to
procure it from Git. It would probably be simpler if a person wanting
to work on the help files were to work on their own local copy.

And what to do if someone on the Docs team finds Help that needs
copyediting, enhancement, etc? Open an issue about it, attaching an
edited/revised version? Edit the Help file directly?

I think the idea would be that someone working on one of the bug
reports would come and discuss the resolution of the problem here on
the ML with the rest of the team, or at least come and ask questions
here when in doubt.

Depending on the length and detail of the answer, this might become
part of an existing chapter of the Contributors Guide, or it could be
a chapter on its own. IMO it's very important to distinguish between
how to work on the Help vs how to work on the user guides.

i think you're right that there should be a dedicated chapter on the
subject, and that it's important to teach newcomers the distinction
between documentation and the software's built-in help.

I'll take this on as a task to do along with revising the Alfresco
content of the contributor docs.

Perhaps both subjects would merit writing-up on the wiki, too, but we
should perhaps be careful about duplicating coverage because of the
probable future emergence of conflicts in the info. With that it mind,
which is the best way to go? Wiki only? Wiki plus contributor docs?
Contributor docs only?

David,
Thanks for the details. Once you got to "checking out the codebase
from Git", I realised why I've never seriously thought about
contributing directly to the Help.

There has been a project for a wiki-based help in the pipeline for a
few months but, for the moment, the work still involves checking out
the codebase from Git and editing files within it.

Depending on the length and detail of the answer, this might become
part of an existing chapter of the Contributors Guide, or it could be
a chapter on its own. IMO it's very important to distinguish between
how to work on the Help vs how to work on the user guides.

i think you're right that there should be a dedicated chapter on the
subject, and that it's important to teach newcomers the distinction
between documentation and the software's built-in help.

I'll take this on as a task to do along with revising the Alfresco
content of the contributor docs.

Perhaps both subjects would merit writing-up on the wiki, too, but we
should perhaps be careful about duplicating coverage because of the
probable future emergence of conflicts in the info. With that it mind,
which is the best way to go? Wiki only? Wiki plus contributor docs?
Contributor docs only?

Ideally both, but given the lack of resources to keep things up to
date, my preference would be to make them "contributor docs" only,
listed on the wiki (and downloadable from there)... only because
that's how I've done the other chapters, all of which are still
incomplete drafts. But I'm open to going the other way, with the info
in wiki format as the primary source.

It's the usual balance between what's preferable and what's most
likely to be achieved.

--Jean

Hi Jean,

Ideally both, but given the lack of resources to keep things up to
date, my preference would be to make them "contributor docs" only,
listed on the wiki (and downloadable from there)... only because
that's how I've done the other chapters, all of which are still
incomplete drafts.

Me, too, I reckon this would be the best solution.

It's the usual balance between what's preferable and what's most
likely to be achieved.

Quite so...

Ngày 11/11/08 2:56, David Nelson vie^'t:

OK. Please can you provide me with the translation into Vietnamese of the word "Vietnamese" plus the description "Content in Vietnamese language"?

Here we go

1. "Vietnamese": Tie^'ng Vie^.t
2. "Content in Vietnamese": No^.i dung ba(`ng Tie^'ng Vie^.t

Cheers,

Nguye^~n Vu~ Hu+ng

Hi Vu Hung,

1. "Vietnamese": Tie^'ng Vie^.t
2. "Content in Vietnamese": No^.i dung ba(`ng Tie^'ng Vie^.t

Thank you for that. :slight_smile: But could you maybe mail it to me off-list in
a .odt file, as the accented characters did not survive the journey?

Thank you if so. :slight_smile:

Hi :slight_smile:
I think the problem with accents migth be that people don't have the right fonts installed. Odt does not embed fonts into documents but Pdf does. Hmm, well "Export to Pdf" doesn't but "Print" - "to file" does.

On Windows, right now, there is a problem with any software that deals with embedded fonts as there is an exploit that a carefully prepared ttf font can used to errr exploit. Their method of dealing with the problem is to block parts of the programs that can handle embedded fonts. So, it's better to get your own fonts for your own systems.

LibreOffice is immune as it doesn't embed fonts and Gnu&Linux is immune because it doesn't use the same fonts parser.

Hopefully the whole problem might be sorted out in a couple of weeks.

Regards from
Tom :slight_smile:

Hi Jean,

My main questions are to do with how and where we write/edit help:

* In the Help files themselves? (If so, where?)

Yes, that would ultimately be the best solution. They are in the git
repository in hc2 (helpcontent2), which one would have to check out and
use one's own local git tree. Once changes had been made, one could
propose integration of patches, as diff or patch files, either attached
to the issue or sent to dev mailing list.

If there are any questions about creating new help content, probably the
best person to ask is Andras Timar. From what I understand, new entries
require creation of a unique node id, so that the help index can be
rebuilt properly at compile time.

My understanding was that at one time it was going to be possible to
just write a new wiki entry in the online wiki help, which would get
converted back into the source code help via some script magic, but I
don't know what became of that. Andras is likely to know more.

Alex

Ngày 11/11/08 17:48, David Nelson vie^'t:

1. "Vietnamese": Tie^'ng Vie^.t
> 2. "Content in Vietnamese": No^.i dung ba(`ng Tie^'ng Vie^.t

Thank you for that.:slight_smile: But could you maybe mail it to me off-list in
a .odt file, as the accented characters did not survive the journey?

I did send you off-list.

By the way, it seems that the mailing list documentation at global.libreoffice.org
converts Vietnamese Unicode characters into VIQR "encode" without my permissions :slight_smile:
<subtle>

Regards,

Nguyen Vu Hung

Hi Vu Hung,

I did send you off-list.

By the way, it seems that the mailing list documentation at
global.libreoffice.org
converts Vietnamese Unicode characters into VIQR "encode" without my
permissions

Thank you, I received the document and now have the translations
intact. I will mail you back as soon as I have finished setting up the
space for you.

As regards the undesirable character conversion, I will raise the
matter with Florian Effenberger to see about a solution. Am I correct
that there is no problem occurring with the Vietnamese mailing list
hosted at http://lists.hanoilug.org/pipermail/du-an-most/ ?

Ngày 11/11/09 12:15, David Nelson vie^'t:

Thank you, I received the document and now have the translations
intact. I will mail you back as soon as I have finished setting up the
space for you.

Thank you.

As regards the undesirable character conversion, I will raise the
matter with Florian Effenberger to see about a solution. Am I correct
that there is no problem occurring with the Vietnamese mailing list
hosted athttp://lists.hanoilug.org/pipermail/du-an-most/ ?

I thought that the reason documentation@global.libreoffice.org converts Vietnamese
Unicode into VIQR is that the list masters want to get rid of MS TTF parsing bugs!?
I hope I was wrong.

HanoiLUG mailing lists run mailman/pipemail on Debian, we set UTF-8 as the
default encoding and there is no problem for 7 years :slight_smile:

Following is a test:

Japanese:???
Chinese:???:slight_smile:
Vietnamese: Tie^'ng Vie^.t hie^?n thi. ?u+o+.c không nhi??