Re: Change .page, see result

[Hannie Dumoleyn]

Hi Germán,
Wow, these sure are encouraging words. I will answer between the lines:

Op 06-12-17 om 13:27 schreef Germán Poo-Caamaño:

Hi Hannie,

I am very sorry that my pointers turned out to be more complex than I
anticipated. I believe I was not clear enough on what I meant.

Let us step back a bit and be sure we are on the same page (no pun
intended with respect to the subject of this thread).

My understanding is that you are already using git, and you have a
branch with your changes in the documentation. Therefore, you want to
know how to submit your changes in bugzilla.
That's right. I use git (clone, add, commit, push, and checkout) to 
upload translations (.po files) to the server.
But now I want to start contributing as a reviewer/author for 
gnome-user-docs and gnome-getting-started-docs as well. I have changed 
gs-use-system-search.page and I have checked the changes on my pc using 
Yelp. From what Ekaterina wrote, I understand that I should not push my 
local branch, gnome-getting-started-docs, to git.gnome.

Instead, I should send a patch to Bugzilla.

I just checked Gunnar's notes, thanks Gunnar!, and I will try the last 
steps (git add *, git commit and git format-patch HEAD~). If it works, 
it will make me very happy indeed :)  If not, I will ask further 
questions on this list or on irc.

Considering that, I meant to say that you should consider only the link
to submit a patch, not the previous steps about building a project
and/or installing Builder or jhbuild.
The reason why I looked at the previous steps is because I could not 
create a patch (step 4). In the example I saw 
nautilus(~/jhbuild/checkout) master, so my conclusion was I should 
install jhbuild first.


Hannie




___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Gunnar Hjalmarsson]

Hannie,

Since I was a beginner a few months ago, with respect to creating a 
properly formatted git patch, I posted the message below, which shows a 
terminal way to do it:


https://lists.ubuntu.com/archives/ubuntu-doc/2017-May/020424.html

It may or may not be useful to you. Myself have returned to that message 
a few times. ;)


--
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj
___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Germán Poo-Caamaño]

On Wed, 2017-12-06 at 11:53 +0100, Hannie Dumoleyn wrote:
> Hello Germán,
> Thanks for the info. In order to be able to submit a patch, I
> followed the instructions on the wiki, [1] . I installed Flatpak
> (version 0.10.1) on Ubuntu 17.10, but I got stuck when trying to
> download Builder (gnome-software message: Don't know how to handle 
> 'file:///tmp/mozilla_hannie0/org.gnome.Builder-2.flatpakref'). I
> will try to install jhbuild instead, according to 'Set up your
> testing environment' [3] and see if that will allow me to submit
> patches.

Hi Hannie,

I am very sorry that my pointers turned out to be more complex than I
anticipated. I believe I was not clear enough on what I meant.

Let us step back a bit and be sure we are on the same page (no pun
intended with respect to the subject of this thread).

My understanding is that you are already using git, and you have a
branch with your changes in the documentation. Therefore, you want to
know how to submit your changes in bugzilla.

Considering that, I meant to say that you should consider only the link
to submit a patch, not the previous steps about building a project
and/or installing Builder or jhbuild.

> I realize that this mailing list is not a helpdesk, so if I am
> asking too much help here, I apologize and I will stop asking
> questions.

You found some roadblocks on your way, but please do not get
discouraged because of them. It may be an opportunity to improve our
documentation for newcomers ;-)

In my personal opinion, the only bad question is the question that is
never asked.

If you feel more comfortable, there is a mailing list especially
dedicated to newcomers:
https://mail.gnome.org/mailman/listinfo/newcomers-list

Also you can ask also on IRC #newcomers or #docs. Feel free to ping me
whenever you see me there (gpoo).

-- 
Germán Poo-Caamaño
http://calcifer.org/

signature.asc
Description: This is a digitally signed message part
___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Hannie Dumoleyn]

Hello Germán,
Thanks for the info. In order to be able to submit a patch, I followed 
the instructions on the wiki, [1] . I installed Flatpak (version 0.10.1) 
on Ubuntu 17.10, but I got stuck when trying to download Builder 
(gnome-software message: Don't know how to handle 
'file:///tmp/mozilla_hannie0/org.gnome.Builder-2.flatpakref'). I will 
try to install jhbuild instead, according to 'Set up your testing 
environment' [3] and see if that will allow me to submit patches.


I realize that this mailing list is not a helpdesk, so if I am asking 
too much help here, I apologize and I will stop asking questions.


Hannie

[1] https://wiki.gnome.org/Newcomers/SubmitPatch
[2] https://wiki.gnome.org/Newcomers/BuildProject
[3] https://wiki.gnome.org/DocumentationProject/Contributing

A patch is a representation of the minimal changes between your file(s)
and the one(s) in the repository. It allows people to focus only in the
changes, rather than looking through a whole file. With a little bit of
practice, you will get used to and you will find it handy (welcome to
the matrix! ;-)

That said, you may want to take a look at:
https://wiki.gnome.org/Newcomers/SubmitPatch


I am currently trying to find out how things work. And I fully
understand that you will only allow me to push minor fixes straight
to master after I have proven I can do it right. I will go through
the buglist to see if I can fix some of them and send my changes, if
any, to Bugzilla.

Another resource (perhaps not as detailed as you are asking) is:
https://wiki.gnome.org/DocumentationProject/Contributing



___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Germán Poo-Caamaño]

Hi Hannie,

On Tue, 2017-12-05 at 17:37 +0100, Hannie Dumoleyn wrote:
> Op 05-12-17 om 12:24 schreef Ekaterina Gerasimova:
> > 
> > > What will happen if I commit/push the branch with the changed
> > > .page files I
> > > am happy with. Will they be added to gnome-user-docs (patches?).
> > > So far, I
> > > have only pushed the branch with changes to the nl.po file.
> > 
> > That is what will happen.
> > 
> > As this would be your first docs contribution, it would be better
> > if
> > you could push a branch for review or attach a patch to Bugzilla.
> > 
> > Generally, after seeing a few good patches and when I'm sure that
> > you're not breaking the build, I am likely to suggest that you
> > start
> > pushing minor fixes straight to master.
> > 
> 
> Hello Ekaterina,
> 
> I understand that it is better NOT to push the gnome-user-docs branch
> if I have changed .page files. Instead, I will attach the .page file
> (or part of it?) to a Bugzilla report (is that what you mean by
> "attaching a patch to Bugzilla?). I do not know how I can push a
> branch for review.

A patch is a representation of the minimal changes between your file(s)
and the one(s) in the repository. It allows people to focus only in the
changes, rather than looking through a whole file. With a little bit of
practice, you will get used to and you will find it handy (welcome to
the matrix! ;-)

That said, you may want to take a look at:
https://wiki.gnome.org/Newcomers/SubmitPatch

> I am currently trying to find out how things work. And I fully 
> understand that you will only allow me to push minor fixes straight
> to master after I have proven I can do it right. I will go through
> the buglist to see if I can fix some of them and send my changes, if
> any, to Bugzilla.

Another resource (perhaps not as detailed as you are asking) is:
https://wiki.gnome.org/DocumentationProject/Contributing

-- 
Germán Poo-Caamaño
http://calcifer.org/

signature.asc
Description: This is a digitally signed message part
___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Hannie Dumoleyn]

Op 05-12-17 om 12:24 schreef Ekaterina Gerasimova:



What will happen if I commit/push the branch with the changed .page files I
am happy with. Will they be added to gnome-user-docs (patches?). So far, I
have only pushed the branch with changes to the nl.po file.

That is what will happen.

As this would be your first docs contribution, it would be better if
you could push a branch for review or attach a patch to Bugzilla.

Generally, after seeing a few good patches and when I'm sure that
you're not breaking the build, I am likely to suggest that you start
pushing minor fixes straight to master.


Hello Ekaterina,

I understand that it is better NOT to push the gnome-user-docs branch if 
I have changed .page files. Instead, I will attach the .page file (or 
part of it?) to a Bugzilla report (is that what you mean by "attaching a 
patch to Bugzilla?). I do not know how I can push a branch for review.


I am currently trying to find out how things work. And I fully 
understand that you will only allow me to push minor fixes straight to 
master after I have proven I can do it right. I will go through the 
buglist to see if I can fix some of them and send my changes, if any, to 
Bugzilla.


Hannie

___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Ekaterina Gerasimova]

On 5 December 2017 at 10:09, Hannie Dumoleyn
 wrote:
> Op 04-12-17 om 19:34 schreef Gunnar Hjalmarsson:
>>
>> On 2017-12-04 17:59, Hannie Dumoleyn wrote:
>>>
>>> I do not know where the help files which I get when I press F1
>>> reside, and I do not want to mess them up. That is why I stored a
>>> copy of gs-use-system-search.page in a separate directory. I can
>>> experiment with it, without messing up the branch I downloaded.
>>
>>
>> Messing with the files you downloaded is exactly what you are supposed to
>> do. yelp can't read a file which isn't located together with the other files
>> (at least index.page must be present in the same directory).
>>
> Hello Gunnar,
>
> This is the right answer :) Thanks. I already thought it was not possible to
> copy a .page file to another directory and then see the result of the
> changes I made using yelp myname.page in the terminal. I wanted to use this
> method to be able to experiment with text, tags, code etc. without ruining
> the branch I downloaded.
>
> What I can do is this: experiment with .page files from the local branch,
> look at the results, and if something is wrong I can delete the branch on my
> local machine and download the branch again from git.
>
> What will happen if I commit/push the branch with the changed .page files I
> am happy with. Will they be added to gnome-user-docs (patches?). So far, I
> have only pushed the branch with changes to the nl.po file.

That is what will happen.

As this would be your first docs contribution, it would be better if
you could push a branch for review or attach a patch to Bugzilla.

Generally, after seeing a few good patches and when I'm sure that
you're not breaking the build, I am likely to suggest that you start
pushing minor fixes straight to master.

> @Andre: thanks for the tip (Ctrl L)
>
> @Jim: your information is helpful too. At this moment I am experimenting
> with .page files from gnome-user-docs and gnome-getting-started, but I may
> also want to work on documentation of applications like gedit.
>
> Hannie
>
>
> ___
> gnome-doc-list mailing list
> gnome-doc-list@gnome.org
> https://mail.gnome.org/mailman/listinfo/gnome-doc-list
___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Hannie Dumoleyn]

Op 04-12-17 om 19:34 schreef Gunnar Hjalmarsson:

On 2017-12-04 17:59, Hannie Dumoleyn wrote:

I do not know where the help files which I get when I press F1
reside, and I do not want to mess them up. That is why I stored a
copy of gs-use-system-search.page in a separate directory. I can
experiment with it, without messing up the branch I downloaded.


Messing with the files you downloaded is exactly what you are supposed 
to do. yelp can't read a file which isn't located together with the 
other files (at least index.page must be present in the same directory).



Hello Gunnar,

This is the right answer :) Thanks. I already thought it was not 
possible to copy a .page file to another directory and then see the 
result of the changes I made using yelp myname.page in the terminal. I 
wanted to use this method to be able to experiment with text, tags, code 
etc. without ruining the branch I downloaded.


What I can do is this: experiment with .page files from the local 
branch, look at the results, and if something is wrong I can delete the 
branch on my local machine and download the branch again from git.


What will happen if I commit/push the branch with the changed .page 
files I am happy with. Will they be added to gnome-user-docs (patches?). 
So far, I have only pushed the branch with changes to the nl.po file.


@Andre: thanks for the tip (Ctrl L)

@Jim: your information is helpful too. At this moment I am experimenting 
with .page files from gnome-user-docs and gnome-getting-started, but I 
may also want to work on documentation of applications like gedit.


Hannie

___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Gunnar Hjalmarsson]

On 2017-12-04 17:59, Hannie Dumoleyn wrote:

I do not know where the help files which I get when I press F1
reside, and I do not want to mess them up. That is why I stored a
copy of gs-use-system-search.page in a separate directory. I can
experiment with it, without messing up the branch I downloaded.


Messing with the files you downloaded is exactly what you are supposed 
to do. yelp can't read a file which isn't located together with the 
other files (at least index.page must be present in the same directory).


--
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj
___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Jim Campbell]

Hi Hannie,

If you're working on a file that will be part of (for example) gedit, and
you've cloned the gedit repository, the documentation would be in
gedit/help/C.  You'd place your new "page" file in the gedit/help/C
directory, and then do "yelp gedit/help/C" and it will launch all of the
gedit help, including the new page file that you just wrote.

You can also launch the individual page by doing 'yelp
gedit/help/C/my-new-page.page'

If you keep yelp running, it will continually refresh your updated 'page'
every time that you save it.

I hope this helps!

Jim

On Mon, Dec 4, 2017 at 11:18 AM, Andre Klapper  wrote:

> Hi,
>
> On Mon, 2017-12-04 at 17:59 +0100, Hannie Dumoleyn wrote:
> > When I add .page to the command
> > ~/gnome/gnome-getting-started$ yelp gs-use-system-search.page
> > I get: unknown error.
>
> If that is a standard Git checkout, then there is simply no file called
> "gs-use-system-search.page" in the top folder of "gnome-getting-
> started". Hence Yelp cannot offer files that do not exist.
>
> > I do not know where the help files which I get when I press F1
> > reside,
>
> Pressing "Ctrl+L" in Yelp will tell you the location. :)
>
> andre
> --
> Andre Klapper  |  ak...@gmx.net
> http://blogs.gnome.org/aklapper/
> ___
> gnome-doc-list mailing list
> gnome-doc-list@gnome.org
> https://mail.gnome.org/mailman/listinfo/gnome-doc-list
>
___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Andre Klapper]

Hi,

On Mon, 2017-12-04 at 17:59 +0100, Hannie Dumoleyn wrote:
> When I add .page to the command
> ~/gnome/gnome-getting-started$ yelp gs-use-system-search.page
> I get: unknown error.

If that is a standard Git checkout, then there is simply no file called
"gs-use-system-search.page" in the top folder of "gnome-getting-
started". Hence Yelp cannot offer files that do not exist.

> I do not know where the help files which I get when I press F1
> reside, 

Pressing "Ctrl+L" in Yelp will tell you the location. :)

andre
-- 
Andre Klapper  |  ak...@gmx.net
http://blogs.gnome.org/aklapper/
___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Hannie Dumoleyn]

Op 04-12-17 om 13:44 schreef Andre Klapper:

On Mon, 2017-12-04 at 11:56 +0100, Hannie Dumoleyn wrote:

I would like to know how I can see the result of the changes I make to a
.page file

You open the .page file in Yelp (GNOME's help browser).

Cheers,
andre


Hi Andre,

Thanks for the answer. I tried this in the Terminal: 
~/gnome/gnome-getting-started$ yelp gs-use-system-search

The result is: Document not found. The URI does not refer to a valid page.

When I add .page to the command
~/gnome/gnome-getting-started$ yelp gs-use-system-search.page
I get: unknown error.

I do not know where the help files which I get when I press F1 reside, 
and I do not want to mess them up. That is why I stored a copy of 
gs-use-system-search.page in a separate directory. I can experiment with 
it, without messing up the branch I downloaded.


Sorry, I am a newbe, so I need more hints :)

Hannie

___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

Re: Change .page, see result

[Andre Klapper]

On Mon, 2017-12-04 at 11:56 +0100, Hannie Dumoleyn wrote:
> I would like to know how I can see the result of the changes I make to a 
> .page file

You open the .page file in Yelp (GNOME's help browser).

Cheers,
andre
-- 
Andre Klapper  |  ak...@gmx.net
http://blogs.gnome.org/aklapper/
___
gnome-doc-list mailing list
gnome-doc-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list