Problems editing help files

I'm trying for the first time to edit a live help file and have come up
against a few problems. *WARNING* I'm a Git virgin so please treat me
kindly.

Firstly, the Git tutorials that I've found assume that all files are in a
single one-level directory structure. Easy for teaching, but not for real
life! I cloned the help files into a local Git repository (that seemed to
work OK) and edited a file.
git status then tells me that help has modified content. If I do "git add
help" git status gives me exactly the same as before,Obviously I'm doing
something wrong, but can't see what it is. Do I have to type the entire path
& file name into the git add command?

Secondly, the LO Writer Help Authoring extension doesn't seem to be acting
as advertised. Previously, I'd tried editing a few local help files, and so
my document root was a test directory. As the wiki suggests I tried changing
this, but the "Help Authoring|Set Document Root" menu item, asks me to set a
directory, but "Help Authoring|Open File" still goes to the old root. Again,
am I doing something wrong, or is there a bug?

Hi Peter

I'm trying for the first time to edit a live help file and have come up
against a few problems. *WARNING* I'm a Git virgin so please treat me
kindly.

Git is the best tool for those who tamed it.

Firstly, the Git tutorials that I've found assume that all files are in a
single one-level directory structure. Easy for teaching, but not for real
life! I cloned the help files into a local Git repository (that seemed to
work OK) and edited a file.

congrats!

git status then tells me that help has modified content. If I do "git add
help"

You only add files that are not yet under git control (e.g. new files).
If you modified an existing file under git control you will see the
differences with

- git diff (will show the diff between the edited file and the one in
the repository)

- git status (will tell you what files have been modified and what file
you have in your workspace that are not under git control)

git status gives me exactly the same as before,Obviously I'm doing

something wrong, but can't see what it is. Do I have to type the entire path
& file name into the git add command?

To submit your changes you must "commit" them to your local copy of git.

git commit file1 file2 file3...
git commit -a (=all modified files that are under git controlled tree)

An editor will open to put your remarks on the changes you did. The
chosen editor depends on your git settings.

Once you save the contents and quit the editor, git commits the changes
in your local copy.

To submit your changes for revision, use git push (you must get a login
in the LO gerrit service.
https://wiki.documentfoundation.org/Development/gerrit )

In summary, it is not that easy for the neophyte. But come to
#libreoffice-dev, #libreoffice-doc in Freenode IRC so we can help you on
the fly.

Secondly, the LO Writer Help Authoring extension doesn't seem to be acting
as advertised. Previously, I'd tried editing a few local help files, and so
my document root was a test directory. As the wiki suggests I tried changing
this, but the "Help Authoring|Set Document Root" menu item, asks me to set a
directory, but "Help Authoring|Open File" still goes to the old root. Again,
am I doing something wrong, or is there a bug?

Although HelpAuthoring has evolved a lot recently and is very usable it
still has some rough edges.

If you edit existing help files you don't need to set the document root,
it is already set for the old root.

P.S. Since I also had all the same issues as you in the begining, I
always save the changed files in a separate folder when I cross an issue
in git/gerrit/logerrit/helpauthoring that I don't uderstand.

I hope this help you a bit

regards

Thanks Olivier. I don't have time now to do an interactive chat. Possibly
next week.

I'm sure that Git is great, but as with all such tools it has to do a lot of
things so it gets complicated fairly quickly. As an ex-software writer I
sympathise with the designer.

But here's a quick excerpt of a console session. There's just one changed
file 4 directories deep from /help/ which is the top level of the clone from
the LO site.

<http://nabble.documentfoundation.org/file/n4180637/GitSession.jpg>

Hello Peter

some remarks
1)
git status: Strange... the modified file should have the full path listed

modified: path/to/file/filename.xhp

2)
git commit -m "3rd party"

You must give the name of the file you modified for commit. That is
git commit -m "3rd party" file1 file2 file3...

3)
git add help

This "help" stuff is already been under git control, no need ot add it
again.

4)
git status
Same as 1.

"git diff" will list the changes you did since last "git pull"

regards

Olivier

Thanks Olivier,

I'm wondering if the problem is that I used Git-GUI to do the initial clone and add/commit rather than the console. And Git-GUI doesn't tell you exactly what it's doing.

One point - Git is installed in my Program Files directory (the default), which Windows protects from casual overwriting. If Git wants to write in this directory, it might fail. Could this be an issue? I'd have expected at least an error message.

2)
OK. But I get the same:
Peter@Peter-PC2 MINGW64 /d/peter/pc/git/lohelp (master)
$ git commit -m "Try 4th time" help
On branch master
Changes not staged for commit:
        modified: help (modified content)

no changes added to commit

Peter@Peter-PC2 MINGW64 /d/peter/pc/git/lohelp (master)
$

4)

$ git diff help
diff --git a/help b/help
--- a/help
+++ b/help
@@ -1 +1 @@
-Subproject commit e22230a873bf0cd2e10746557f6d0003ee7a9859
+Subproject commit e22230a873bf0cd2e10746557f6d0003ee7a9859-dirty

Best regards,

Peter
mailto:lo@ptoye.com
www.ptoye.com