RE: Document Update Instructions have been revised

[Chris Good]

> -Original Message-
> From: David T. [mailto:sunfis...@yahoo.com]
> Sent: Saturday, 21 January 2017 6:38 PM
> To: Chris Good 
> Cc: GnuCash Developers 
> Subject: Re: Document Update Instructions have been revised
> 
> Chris, Geert,
> 
> I have to admit that I have put off reading through the changes that you’ve
> collectively put in on this wiki page, in part because I am *that* 
> contributor—
> you know, the one who barely understands what he is doing, and is wary of
> changing the way he does something for fear that it will break and never
> work again.
> 
> I have begun to work through this page one more time, and I will no doubt
> have changes and suggestions later on. I will refer to my sentence above,
> however, and note that my editorial inclinations are limited by my limited
> understanding of the technologies and expectations for this process
> generally.
> 
> I have a few top level comments:
> 
> A - This page has gotten quite large. Should it be broken into smaller pieces?
> 
> B - I would like to see this page separate out the different aspects of the
> process more cleanly. Currently, it seems that the set up of the technologies,
> the application of the technologies, and the practices we use are all
> intermingled. This makes it harder to focus on one aspect. For example,
> Steps 2-5 should be separated out into a separate page on setting up Git for
> use with documentation.
> 
> C - I think the Preface should outline as simply as possible the overall 
> process,
> which I understand to be:
> 
> 1) Contributors propose changes using Bugzilla.
> 2) Contributors use a VCS (git), to make these changes locally.
> 3) Changes are validated locally.
> 4) Contributors submit these changes for approval.
> 5) Changes are approved and incorporated into the doc set.
> 
> This overview could then be used to structure the remaining sections.
> 
> I think that the information that currently resides in the Preface is useful,
> however, and I’d like to see it moved into other areas as appropriate.
> 
> D - Upon initial examination, I see that all reference to how it used to be
> done (i.e., the individual xslt and xmllint commands) has been removed from
> the page. While I understand that you two believe that this is the right way 
> to
> move forward, it leaves me in a quandary. I already have a local copy, and I
> know that I can issue some commands to check and compile my local copy,
> but I always refer back to the wiki for the exact commands, which you’ve
> removed. I would prefer that some inclusion of these other methods be
> mentioned in some way.
> 
> I began to make some of these changes myself, but given my limited abilities
> with these processes, I thought it better to discuss the changes here before
> unilaterally (and ill-informedly) making the changes directly.
> 
> David
> 
> > On Jan 17, 2017, at 5:16 AM, Chris Good 
> wrote:
> >
> > Hi,
> >
> >
> >
> > I've finished updating the wiki Document Update Instructions [1] to
> > include instructions for using 'make' rather than xmllint and xsltproc
> directly.
> >
> > Thank you very much Geert for all the info.
> >
> >
> >
> > [1] http://wiki.gnucash.org/wiki/Documentation_Update_Instructions
> >
> >
> >
> > Regards, Chris Good

Hi David,

A - IMHO I don't think this page is too large. It is quite easy to navigate 
using the index at the top. It would be annoying to have to jump to multiple 
pages.

B - I agree it could be better structured. I don't think it needs a new page. 
If you're going to put 3.2 to 3.5 into a separate git set up section, it would 
be good if you could include some instructions on how to start a new 
modification (including rebasing) having already set up git and your build 
directory structure previously.

I previously created Git_For_Newbies with the idea that new users should really 
be using that for all the git stuff (using Pull Requests instead of Patches if 
possible). Git_For_Newbies applies equally to the documentation as to the 
programs. I haven't gotten around to fixing Documentation_Update_Instructions 
yet. If you can, Great! :-) It may be that much of Git_For_Newbies needs to be 
brought into Documentation_Update_Instructions but changed to specifically 
refer to the documentation. But that seems like a lot of duplication...

C - Having an additional outline as you suggest may be helpful, although the 
index already gives a 1 page summary - on my new 27" monitor anyway :-). I'm 
not sure I agree with moving the stuff already in the Preface into other areas. 
I think it is useful to get some detail of what is involved before reading 
everything.

D - Why do you need the original xmllint + xsltproc commands? Don't the 'make' 
commands work for you? In my experience, 'make' is installed by default in all 
the Linux distros I've used (not many I admit). Is that not the case in Mac 
OSX? You can create a build directory 

Re: Wiki URL

[Derek Atkins]

Hi,

On Sat, January 21, 2017 7:02 pm, Frank H. Ellenberger wrote:
> Hi David,
>
> Am 21.01.2017 um 08:21 schrieb David T. via gnucash-devel:
>> Hi,
>>
>> Could someone explain why the URL wiki.gnucash.org
>>  doesn’t point to the wiki? Seems to me, if I
>> type “wiki.gnucash.org ” in the address bar,
>> I’m looking for the wiki…
>>
>> David
>
> because it is only an alias of code.gnucash.org.

Exactly.  wiki == cvs == lists == code == svn.  All one machine, with one
common HTTP config.  Indeed, until I added SSL there were no separate
names for the server within the apache configuration.  There are separate
names  in DNS for potential future "split off the features" but it's
currently one server.

> Derek, could you "forward" wiki.gnucash.org to wiki.gnucash.org/wiki?

I'm honestly not sure how to do that without breaking links.  If I change
the document root to the wiki location then other links (that assume the
common document root) may break, or it may open up a security hole.  I'm
also not sure how to set up a redirect for a particular name's root.  Tell
me how to do it and I'll gladly implement it.

This is why there is a link to the wiki from the landing page you reach
when you hit the document root.

> Frank

-derek

-- 
   Derek Atkins 617-623-3745
   de...@ihtfp.com www.ihtfp.com
   Computer and Internet Security Consultant

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Wiki URL

[Frank H. Ellenberger]

Hi David,

Am 21.01.2017 um 08:21 schrieb David T. via gnucash-devel:
> Hi,
> 
> Could someone explain why the URL wiki.gnucash.org  
> doesn’t point to the wiki? Seems to me, if I type “wiki.gnucash.org 
> ” in the address bar, I’m looking for the wiki…
> 
> David

because it is only an alias of code.gnucash.org.

Derek, could you "forward" wiki.gnucash.org to wiki.gnucash.org/wiki?

Frank

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Document Update Instructions have been revised

[David T. via gnucash-devel]

> On Jan 18, 2017, at 8:06 AM, Chris Good  wrote:
> 
>> 
>> * Lastly you describe how to format a patch. While this is certainly one
> of the
>> accepted methods, it may be interesting to document how to make a pull
>> request as well.
>> 
>> That's it. Again, thanks for all the effort you spent on this so far!
>> 
>> Regards,
>> 
>> Geert
> 

It seems to me that this instruction set is meant for new contributors to the 
documentation. Personally, I think such a set of instructions should focus 
primarily on ONE method for contributing, with passing mention of other 
possibilities. As I understand it, the git way is the currently-preferred 
method for offering contributions, and IMHO, this wiki page should focus 
primarily on that. Passing mention of other methods can be included for those 
who already have the understanding of the technologies. Thus, the discussions 
about formatting a patch and attaching it to the bug could be mentioned in 
passing, while the git pull request method could be brought forward and 
promoted.

In the same spirit of giving simpler advice to new contributors, I would prefer 
that the git process described here refer to the other Git page 
(wiki.gnucash.org/wiki/Git ), which I think 
should be cleaned up by someone who knows more about git than I do. 

FWIW, I think the other Git page should focus on one preferred git modality, 
said modality being the one where contributors fork the main GC repository on 
github.com , push their changes to that fork, and then 
issue pull requests to the main repo. Again, other options could be mentioned 
in passing, but the focus should be on the GnuCash Preferred Method.

As for the whole “testing the help on Linux” section, as a Mac user, I have 
NEVER attempted any of this, and if it is an important part of the 
documentation creation process, then I haven’t  done it correctly ever. Since I 
have been successfully adding to the documentation for a while now, I can 
assume that this section is, in fact, superfluous to the actual documentation 
update process. I would propose moving it into some other area of the wiki, 
perhaps with an advanced Linux developer’s page, where true geeks (I say this 
with admiration) can plumb the depths of providing this added Linux 
functionality. 

David

> Hi Geert,
> 
> Thanks for reviewing my work and adding extra suggestions. I really enjoy
> learning more from your insights. I like to know, at least generally, 'why',
> as well as 'how'.
> I totally agree your suggestions would be helpful to new documenters. I'm a
> little concerned that the bulk of this page could be a little off-putting.
> However, I think it is better to have too much info than not enough.
> I would like to point out that your suggestions are mostly changes to things
> other people wrote. :-)
> 
> Originally, I myself started to try to modify the documentation on Windows
> but soon thought it was not possible (or at least too difficult), and
> changed to Linux.
> People who are not familiar with Linux and virtual machines would probably
> like more guidance on this.
> I have since found that xmllint.exe & xsltproc.exe are in
> c:\strawberry\c\bin so that may help. Maybe an msys (or cygwin?) environment
> is not needed. I know practically nothing about msys or cygwin. If anyone
> else can add anything about updating the documentation on Windows or Mac,
> I'd like to hear it.
> 
> Re the various translations:
> I only speak 1 language, English (Australian) fluently, and some will argue
> about that, so it has never really mattered to me, but...
> Is it true that the non-English versions of the documentation are
> translations of the English documentation?
> If so, is this 'policy' or just how it has worked out?
> I could imaging that different translations could have totally unique
> sections to cater for localisations.
> 
> I agree it should be made clearer that it is only necessary to build and
> install a development version of GnuCash (programs) if one needs to test
> context help for features that are only in a more recent version than
> already installed. That section has always been confusing to me.
> 
> 'Step 2 Git Clone' links to info about using pull requests instead of
> patches.
> I'll add similar references to the start of ' Step 15 Prepare your Patch'.
> 
> Regards, Chris Good
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel