Some Assistance Please

classic Classic list List threaded Threaded
30 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Some Assistance Please

GnuCash - Dev mailing list
Hello,

Once again, the documentation bug has bit me, and I am trying to use the accepted GnuCash toolset to implement a change to the Guide.

Most recently, this toolset has been changed to use “make”, and when I attempt to refresh my memory by going to the wiki page, I fail to find an explanation that makes sense to me.

My environment is as follows:

OS: Mac
Git clone saved in ~/Development/Gnucash/docs
Build directory in ~/Development/GnuCash/build
upstream: github.com/Gnucash/gnucash-docs
origin: github.com/sunfish62/gnucash-docs

Specifically, if I have an already-existing installation of the downloaded documentation source that I have pushed and pulled into alignment with github, and I have finished editing the source files, what are the precise commands I need to invoke to get a tested and compiled local documentation set?

Today, I used “make check” from ~/Development/Gnucash/docs/guide/C and all seemed to work; I got no errors following the actual xmllint command. When I changed over to ~/Development/GnuCash/build/guide/C and entered “make html” (per the wiki), I received an error:

configure: error: source directory already configured; run "make distclean" there first

I went to the docs folder and entered “make distclean” and got some output. I then returned to build/guide/C and tried again. I get the same error. No combination of make commands seems to move the process along.

Thanks,
David

P.S.: I continue to think that the wiki page is poorly-constructed for general users. In specific, I object to the high-level structure that embeds the initial setup steps with the ongoing editorial process. In my situation, I find it impossible to separate the setup commands from those that I actually need to proceed.
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Frank H. Ellenberger-3
David,

Am 25.04.2017 um 16:33 schrieb David T. via gnucash-devel:

> Hello,
>
> Once again, the documentation bug has bit me, and I am trying to use
> the accepted GnuCash toolset to implement a change to the Guide.
>
> Most recently, this toolset has been changed to use “make”, and when
> I attempt to refresh my memory by going to the wiki page, I fail to
> find an explanation that makes sense to me.
>
> My environment is as follows:
>
> OS: Mac Git clone saved in ~/Development/Gnucash/docs Build directory
> in ~/Development/GnuCash/build

Here I would use ~/Development/GnuCash/docs/build to avoid collisions,
when you later might checkout other projects like e.g.
github.com/Gnucash/gnucash-on-osx
With your structure after running autogen.sh the commands would be
cd ../build
../docs/configure ...
cd ../docs/guide/C/
(edit)
cd ../build/guide/C/
make check
make html
[make install]

> upstream: github.com/Gnucash/gnucash-docs origin:
> github.com/sunfish62/gnucash-docs
>
> Specifically, if I have an already-existing installation of the
> downloaded documentation source that I have pushed and pulled into
> alignment with github, and I have finished editing the source files,
> what are the precise commands I need to invoke to get a tested and
> compiled local documentation set?
>
> Today, I used “make check” from ~/Development/Gnucash/docs/guide/C
> and all seemed to work; I got no errors following the actual xmllint
> command. When I changed over to ~/Development/GnuCash/build/guide/C
> and entered “make html” (per the wiki), I received an error:

Huh, makefile.am and makefile.in are in the source tree, but real
makefile(s) should only appear in your build tree. If I am in the source
tree, I get:

> make
make: *** No targets specified and no makefile found.  Stop.

or

> make check
make: *** No rule to make target 'check'.  Stop.

If you can run make in your source tree, then you once had run configure
without a build dir and should now clean your source tree.
See the help page of 'git clean' for details.

Your developement environment might have stored some project related
settings in hidden files in your source dir, which you do not want to loose.

> configure: error: source directory already configured; run "make
> distclean" there first
>
> I went to the docs folder and entered “make distclean” and got some
> output. I then returned to build/guide/C and tried again. I get the
> same error. No combination of make commands seems to move the process
> along.

“make distclean” is the counterpart of "make dist", which again will
finally create some compressed Tape ARchive.

> Thanks, David
>
> P.S.: I continue to think that the wiki page is poorly-constructed
> for general users. In specific, I object to the high-level structure
> that embeds the initial setup steps with the ongoing editorial
> process. In my situation, I find it impossible to separate the setup
> commands from those that I actually need to proceed.

The page was created by Tbullock, a documenter like you. Devs mostly
touched it, when changes happend like switch from svn to git. So feel
free to improve it.

Frank

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Geert Janssens-4
In reply to this post by GnuCash - Dev mailing list
On dinsdag 25 april 2017 16:33:37 CEST David T. via gnucash-devel wrote:

> Hello,
>
> Once again, the documentation bug has bit me, and I am trying to use the
> accepted GnuCash toolset to implement a change to the Guide.
>
> Most recently, this toolset has been changed to use “make”, and when I
> attempt to refresh my memory by going to the wiki page, I fail to find an
> explanation that makes sense to me.
>
> My environment is as follows:
>
> OS: Mac
> Git clone saved in ~/Development/Gnucash/docs
I will refer to the above directory as your source directory later on. And any
path below this directory is part of what I call your source tree.
> Build directory in ~/Development/GnuCash/build
Similarly here, I'll be referring to a build directory and build tree.

> upstream: github.com/Gnucash/gnucash-docs
> origin: github.com/sunfish62/gnucash-docs
>
> Specifically, if I have an already-existing installation of the downloaded
> documentation source that I have pushed and pulled into alignment with
> github, and I have finished editing the source files, what are the precise
> commands I need to invoke to get a tested and compiled local documentation
> set?
>
> Today, I used “make check” from ~/Development/Gnucash/docs/guide/C and all
> seemed to work; I got no errors following the actual xmllint command.

This suggests you have run the configure command from one of the directories
in your source tree. From the errors you mention this may be in
~/Development/Gnucash/docs/guide/C

By doing so you may have implicitly configured your source directory resulting
in the errors below. As a rule of thumb, avoid running any "make" command in
your source tree. The only commands that make sense there are git commands to
manage your commits (including pushing and pulling from/to upstream) and "./
autogen.sh" in the root level of your source tree.

"configure" on the other hand should always be called from within the root of
your build directory. From then on "make <whatever>" can be called from any
directory in your build tree.

And to avoid any confusion "from within the root of your build directory"
means you cd into your build directory and then invoke configure. As configure
itself is not in your build directory, but in your source directory, you'll
need to call it with its full path. This gives:
cd ~/Development/GnuCash/build
~/Development/Gnucash/docs/configure

> When
> I changed over to ~/Development/GnuCash/build/guide/C and entered “make
> html” (per the wiki), I received an error:
>
> configure: error: source directory already configured; run "make distclean"
> there first
>
> I went to the docs folder and entered “make distclean” and got some output.
> I then returned to build/guide/C and tried again. I get the same error. No
> combination of make commands seems to move the process along.

You may have to call make distclean directly in
~/Development/GnuCash/build/guide/C
if that is where you accidentally ran configure from before. Note you will
only be able to run make distclean successfully once in each configured
directory. That command will throw away all filed that were automatically
generated by autogen.sh and configure (not your manual changes to the source
files though, which is good).

If you hesitate which directories you may have run configure in, you can
search for a file called config.log. Each directory that contains this file
was at some point in the past "configured" as the error message suggests. With
the exception of your true build directory in each of these directories you
can run make distclean once.

That's one approach to clean up, using the tools provided by make and friends
itself. Another approach would be to use git instead. Git knows which files
belong in your source tree and which ones are generated.

*** Important *** If you want to use the git way, first make sure *all* your
current changes are committed at least locally. That is all your changes
should have been git add'ed and git commit'ed. git status should only show you
untracked files for which you know you didn't edit/create them manually.
Anything that's not committed will be deleted.

From there on it's easy.
Cd into your source directory
run "git clean -fx"
rerun "./autogen.sh"
cd into your build directory
run ~/Development/Gnucash/docs/configure
cd to wherever in your build tree you want to run a make command
execute the make command

>
> Thanks,
> David
>
> P.S.: I continue to think that the wiki page is poorly-constructed for
> general users. In specific, I object to the high-level structure that
> embeds the initial setup steps with the ongoing editorial process. In my
> situation, I find it impossible to separate the setup commands from those
> that I actually need to proceed.

I sympathize. Unfortunately I'm no longer in a position to be able to estimate
what works for general users as you call it. It seems this is also a variable
term. Some users like lots of context, others prefer a short list of commands.
What structure would you propose ? Are you willing to attempt a restructuring
of the page to something you see better fit ? Don't worry if some of the info
your would write there is not completely correct. We can adjust this as we
continue. I just would love to find a structure that works well for a wide
audience first.

Regards,

Geert
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

GnuCash - Dev mailing list
Geert,

See below.

> On Apr 26, 2017, at 5:54 PM, Geert Janssens <[hidden email]> wrote:
>
> By doing so you may have implicitly configured your source directory resulting
> in the errors below. As a rule of thumb, avoid running any "make" command in
> your source tree. The only commands that make sense there are git commands to
> manage your commits (including pushing and pulling from/to upstream) and "./
> autogen.sh" in the root level of your source tree.
>
> "configure" on the other hand should always be called from within the root of
> your build directory. From then on "make <whatever>" can be called from any
> directory in your build tree.
>
> And to avoid any confusion "from within the root of your build directory"
> means you cd into your build directory and then invoke configure. As configure
> itself is not in your build directory, but in your source directory, you'll
> need to call it with its full path. This gives:
> cd ~/Development/GnuCash/build
> ~/Development/Gnucash/docs/configure
>
>> When
>> I changed over to ~/Development/GnuCash/build/guide/C and entered “make
>> html” (per the wiki), I received an error:
>>
>> configure: error: source directory already configured; run "make distclean"
>> there first
>>
>> I went to the docs folder and entered “make distclean” and got some output.
>> I then returned to build/guide/C and tried again. I get the same error. No
>> combination of make commands seems to move the process along.
>
> You may have to call make distclean directly in
> ~/Development/GnuCash/build/guide/C

> if that is where you accidentally ran configure from before. Note you will
> only be able to run make distclean successfully once in each configured
> directory. That command will throw away all filed that were automatically
> generated by autogen.sh and configure (not your manual changes to the source
> files though, which is good).
>
> If you hesitate which directories you may have run configure in, you can
> search for a file called config.log. Each directory that contains this file
> was at some point in the past "configured" as the error message suggests. With
> the exception of your true build directory in each of these directories you
> can run make distclean once.

I attempted to use the above directions, without any success.

>
> That's one approach to clean up, using the tools provided by make and friends
> itself. Another approach would be to use git instead. Git knows which files
> belong in your source tree and which ones are generated.
>
> *** Important *** If you want to use the git way, first make sure *all* your
> current changes are committed at least locally. That is all your changes
> should have been git add'ed and git commit'ed. git status should only show you
> untracked files for which you know you didn't edit/create them manually.
> Anything that's not committed will be deleted.
>
> From there on it's easy.
> Cd into your source directory
> run "git clean -fx"
> rerun "./autogen.sh"
> cd into your build directory
> run ~/Development/Gnucash/docs/configure
> cd to wherever in your build tree you want to run a make command
> execute the make command
>

This set of directions worked.

>
> I sympathize. Unfortunately I'm no longer in a position to be able to estimate
> what works for general users as you call it. It seems this is also a variable
> term. Some users like lots of context, others prefer a short list of commands.
> What structure would you propose ? Are you willing to attempt a restructuring
> of the page to something you see better fit ? Don't worry if some of the info
> your would write there is not completely correct. We can adjust this as we
> continue. I just would love to find a structure that works well for a wide
> audience first.

I am somewhat hesitant to take this on; my experience editing Gnucash wiki pages is decidedly negative. When last I engaged in the editorial process on this particular page, my perspective was not considered relevant to the focus of the page. And recently, changes I made to the Glossary were determined to be incorrect, and the bulk of them removed altogether. I am not interested in putting in the effort of editing a complex wiki document only to have that work discarded.

David

>
> Regards,
>
> Geert

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Frank H. Ellenberger-3
David,

I am really sorry, but you and 2 other authors got by accident a
ninja-like status for a few month in the wiki. So your changes did not
appear on
http://wiki.gnucash.org/wiki/Special:RecentChanges . Else we would have
given you earlier some advice, were we thought your changes might have
issues.

And I am pretty sure, I and almost every other contributor has made some
mistakes, special at the beginning and will more than likely do others
in the future.

Am 26.04.2017 um 18:51 schrieb David T. via gnucash-devel:
> I am somewhat hesitant to take this on; my experience editing Gnucash
> wiki pages is decidedly negative. When last I engaged in the
> editorial process on this particular page, my perspective was not
> considered relevant to the focus of the page.

I do not remember what you are referring here.

> And recently, changes I made to the Glossary were determined to be
> incorrect, and the bulk of them removed altogether. I am not
> interested in putting in the effort of editing a complex wiki
> document only to have that work discarded.

Are you talking about this changeset?
http://wiki.gnucash.org/wiki/index.php?title=Glossary&type=revision&diff=12417&oldid=12414

From the view of documentation writer it is a good idea to convert the
glossary from the wiki into chapter of the docs and replace the wiki
content by a link to the chapter in the docs, to have only one place to
maintain.

OTOH, a note is much faster published via the wiki than over the docs:
* Is my git repo up to date?
* Which branch should I use in this case?
* Which docbooks tags should I use?
* which make commands are required?
* Which git commands are required?

As another aspect: it is usually much faster to create a wiki link than
an external link.

And there are entries like "g-wrap" which would be annoying in the
official docs, because they are obsolete. But while traveling through
the source tree or searching something else in the email archive you
might find notes referencing this term. Then, IMHO, the wiki glossary
should tell you "(replaced by swig for gnucash >= 2.2.0)"

HTH
Frank
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

GnuCash - Dev mailing list
Frank,

I don't know what you mean by "ninja status", and I don't particularly care, but I do know that without some mechanism for resolving disagreements on content, a wiki doesn't really function well, since it leaves the resolution of such disagreements to the person who is willing to push harder for their way. As far as I have seen, GnuCash’s wiki lacks such mechanisms.

David

P.S. This isn’t the venue to discuss our differences about the Wiki Glossary again.

On Thu, Apr 27, 2017 at 3:35, Frank H. Ellenberger
<[hidden email]> wrote:
David,

I am really sorry, but you and 2 other authors got by accident a
ninja-like status for a few month in the wiki. So your changes did not
appear on
http://wiki.gnucash.org/wiki/Special:RecentChanges  <http://wiki.gnucash.org/wiki/Special:RecentChanges>. Else we would have
given you earlier some advice, were we thought your changes might have
issues.

And I am pretty sure, I and almost every other contributor has made some
mistakes, special at the beginning and will more than likely do others
in the future.

Am 26.04.2017 um 18:51 schrieb David T. via gnucash-devel:
> I am somewhat hesitant to take this on; my experience editing Gnucash
> wiki pages is decidedly negative. When last I engaged in the
> editorial process on this particular page, my perspective was not
> considered relevant to the focus of the page.

I do not remember what you are referring here.


> And recently, changes I made to the Glossary were determined to be
> incorrect, and the bulk of them removed altogether. I am not
> interested in putting in the effort of editing a complex wiki
> document only to have that work discarded.


Are you talking about this changeset?
http://wiki.gnucash.org/wiki/index.php?title=Glossary&type=revision&diff=12417&oldid=12414 <http://wiki.gnucash.org/wiki/index.php?title=Glossary&type=revision&diff=12417&oldid=12414>

From the view of documentation writer it is a good idea to convert the
glossary from the wiki into chapter of the docs and replace the wiki
content by a link to the chapter in the docs, to have only one place to
maintain.

OTOH, a note is much faster published via the wiki than over the docs:
* Is my git repo up to date?
* Which branch should I use in this case?
* Which docbooks tags should I use?
* which make commands are required?
* Which git commands are required?

As another aspect: it is usually much faster to create a wiki link than
an external link.

And there are entries like "g-wrap" which would be annoying in the
official docs, because they are obsolete. But while traveling through
the source tree or searching something else in the email archive you
might find notes referencing this term. Then, IMHO, the wiki glossary
should tell you "(replaced by swig for gnucash >= 2.2.0)"

HTH
Frank

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Wiki decision workflow; was: Some Assistance Please

Frank H. Ellenberger-3
David,

Am 27.04.2017 um 14:01 schrieb David T.:

> Frank,
>
> I don't know what you mean by "ninja status", and I don't
> particularly care, but I do know that without some mechanism for
> resolving disagreements on content, a wiki doesn't really function
> well, since it leaves the resolution of such disagreements to the
> person who is willing to push harder for their way. As far as I have
> seen, GnuCash’s wiki lacks such mechanisms.
>
> David

let me try to describe the current state:

some of us watch almost daily
http://wiki.gnucash.org/wiki/Special:RecentChanges
to prevent spam and avoid misleading information.

(That is the place, where your commits didn't appear in the first
quarter year of your activity, so you were almost invisible like a ninja.)

If we are unshure, how to handle a special case, we collect opinions on
irc://irc.gimp.org/gnucash
usually at european evening/american afternoon time.

If a problem is more comlex, we open a bugilla entry to collect the
different aspects.

If we think we need a broader base to find a decision we open a thread
at gnucash-devel if mostly contributors are affected or gnucash-user else.

If I reedit a commit of a serious user, not a spammer, and the reason is
not obvious by my commit, I add a note on the users talk page.

Perhaps I should add the hint "Feel free to open a discussion on the
respective mailing list."

How, do you think, can we improve this?

Frank

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Wiki decision workflow; was: Some Assistance Please

GnuCash - Dev mailing list
So, apparently, there is a decision-making process in place. I’m not sure how it might be improved, since this is quite literally the first I have heard about it.

Since you seem to be one of the folks in charge of the decisions on the wiki, perhaps *you* might consider how to improve the process, so that you encourage engagement, rather than discourage it.

David

> On Apr 27, 2017, at 7:49 PM, Frank H. Ellenberger <[hidden email]> wrote:
>
> David,
>
> let me try to describe the current state:
>
> some of us watch almost daily
> http://wiki.gnucash.org/wiki/Special:RecentChanges
> to prevent spam and avoid misleading information.
>
> (That is the place, where your commits didn't appear in the first
> quarter year of your activity, so you were almost invisible like a ninja.)
>
> If we are unshure, how to handle a special case, we collect opinions on
> irc://irc.gimp.org/gnucash
> usually at european evening/american afternoon time.
>
> If a problem is more comlex, we open a bugilla entry to collect the
> different aspects.
>
> If we think we need a broader base to find a decision we open a thread
> at gnucash-devel if mostly contributors are affected or gnucash-user else.
>
> If I reedit a commit of a serious user, not a spammer, and the reason is
> not obvious by my commit, I add a note on the users talk page.
>
> Perhaps I should add the hint "Feel free to open a discussion on the
> respective mailing list."
>
> How, do you think, can we improve this?
>
> Frank
>

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Wiki decision workflow; was: Some Assistance Please

Geert Janssens-4
On zaterdag 29 april 2017 09:03:54 CEST David T. via gnucash-devel wrote:
> So, apparently, there is a decision-making process in place. I’m not sure
> how it might be improved, since this is quite literally the first I have
> heard about it.
>
> Since you seem to be one of the folks in charge of the decisions on the
> wiki, perhaps *you* might consider how to improve the process, so that you
> encourage engagement, rather than discourage it.
>
> David

David,

I'm sorry you had such a bad experience editing the wiki.

Perhaps part of it is due to expectations. So far the wiki has always been an
informal place to share information. And I have always felt the fact there's
no formal decision making process lowers the barrier for entry rather than
increasing it.

That means that I'm equally "guilty" at loosely editing other people's
contributions there without giving it much thought. I that offended you,
please accept my apologies as well. An the other hand given my expectations I
don't mind if others do the same with my work. Until now I never heard anybody
complain about this.

When I don't agree with changes made by others to my work, this can always be
discussed and optionally reverted. I have on occasion also reverted my own
changes after discussion.

Perhaps you consider my view is wrong and shortsighted. I'm sharing it anyway
as a data point towards a better understanding of how to treat the wiki in the
future.

Regards,

Geert
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Derek Atkins
In reply to this post by GnuCash - Dev mailing list
David,

First, sorry to come at this late...

"David T. via gnucash-devel" <[hidden email]> writes:

> Hello,
>
> Once again, the documentation bug has bit me, and I am trying to use
> the accepted GnuCash toolset to implement a change to the Guide.

Excellent.  Thank you for your ongoing support!!

> Most recently, this toolset has been changed to use “make”, and when I
> attempt to refresh my memory by going to the wiki page, I fail to find
> an explanation that makes sense to me.

I would just point out that this hasn't changed.  This method has been
in place for well over a decade, probably closer to two.

[snip]
> P.S.: I continue to think that the wiki page is poorly-constructed for
> general users. In specific, I object to the high-level structure that
> embeds the initial setup steps with the ongoing editorial process. In
> my situation, I find it impossible to separate the setup commands from
> those that I actually need to proceed.

As the guy who maintains the wiki instance (I run the hardware/OS for
the wiki and maintain the mediawiki software installation), I'm not sure
I understand what you mean by "separate the setup commands from those
that [you] actually need to proceed".  What do you mean by this?  Also,
what do you mean by "high level structure that embeds the initial setup
steps with the ongoing editorial process."?

In a wiki, there's two processes:

1) Account Setup.  You register for an account, and either that account
   is approved or not.  Part of this process requires you to validate
   your email account; another part of this process requires an admin to
   approve you.  This is all done in an attempt to reduce the amount of
   spam.

2) Page Edit.  Once you're registered and approved, you can go an edit
   pages willy-nilly, except for a few "locked" pages.  This should be
   as simple as clicking "Edit" on a page view and then making the
   changes, clicking "Preview" to make sure they look right, and then
   saving them.

There is also an editorial process in place where people like Frank,
John, and Geert look through the changes that have been made and ensure
they are "correct".  Sometimes an incorrect change will be reverted.
But it also allows people to see what changes have been made and check
them, comment on them, etc.

Unfortunately there's something going on where a number of changes are
not showing up in the list of recent changes.  I believe this is the
"ninja status" to which Frank referred -- changes you were making would
not show up in the list of recent changes.  I honestly have no idea why,
and I don't know if this has been corrected.

Note that you can go and READ the wiki pages without an account, you
just can't edit them.

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

GnuCash - Dev mailing list

> On May 2, 2017, at 8:16 PM, Derek Atkins <[hidden email]> wrote:
>
> David,
>
> First, sorry to come at this late...
>
> "David T. via gnucash-devel" <[hidden email]> writes:
>
>> Hello,
>>
>> Once again, the documentation bug has bit me, and I am trying to use
>> the accepted GnuCash toolset to implement a change to the Guide.
>
> Excellent.  Thank you for your ongoing support!!
>
>> Most recently, this toolset has been changed to use “make”, and when I
>> attempt to refresh my memory by going to the wiki page, I fail to find
>> an explanation that makes sense to me.
>
> I would just point out that this hasn't changed.  This method has been
> in place for well over a decade, probably closer to two.

OK, I think the page on the wiki has been changed to prefer the make toolset in recent times.

>
> [snip]
>> P.S.: I continue to think that the wiki page is poorly-constructed for
>> general users. In specific, I object to the high-level structure that
>> embeds the initial setup steps with the ongoing editorial process. In
>> my situation, I find it impossible to separate the setup commands from
>> those that I actually need to proceed.
>
> As the guy who maintains the wiki instance (I run the hardware/OS for
> the wiki and maintain the mediawiki software installation), I'm not sure
> I understand what you mean by "separate the setup commands from those
> that [you] actually need to proceed".  What do you mean by this?  Also,
> what do you mean by "high level structure that embeds the initial setup
> steps with the ongoing editorial process.”?

Here’s what I mean:

On the Documentation Update instructions, section 3 contains 17 different steps.

Step 3.1: Create a Bugzilla Bug is a step that should be undertaken with every proposed change to the documentation.

Step 3.2: Clone the Documentation, however, is (presumably) a one-time setup. Steps 3.3-3.5 similarly are one-time setups (unless you’re a screwup like me, and then you get to do them over and over again).

Steps 3.6-3.10 are again repeated for each change to the docs.

Step 3.11 is a step that is not technically part of the documentation process at all, since it only applies to one family of GnuCash’s supported operating systems. Mac and Windows writers don’t perform this step, and the fact that I have been contributing changes for years without conducting these tests underscores the fact that they aren’t a required part of the Documentation Update process.

Steps 3.12 and following are back to steps taken on each change—although at this point, I wonder whether people are preparing patches and attaching them to Bugzilla bugs (steps 3.15-3.17), or whether everyone has moved to the Github pull request method.

I’ll leave the rest of the topic chalked up to one of those online moments when I saw and felt things that probably were not intended by anyone in the way I took them.

David

>
> -derek
>
> --
>       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
>       Member, MIT Student Information Processing Board  (SIPB)
>       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
>       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Geert Janssens-4
On dinsdag 2 mei 2017 18:10:35 CEST David T. via gnucash-devel wrote:

> Here’s what I mean:
>
> On the Documentation Update instructions, section 3 contains 17 different
> steps.
>
> Step 3.1: Create a Bugzilla Bug is a step that should be undertaken with
> every proposed change to the documentation.
>
> Step 3.2: Clone the Documentation, however, is (presumably) a one-time
> setup. Steps 3.3-3.5 similarly are one-time setups (unless you’re a screwup
> like me, and then you get to do them over and over again).
>
> Steps 3.6-3.10 are again repeated for each change to the docs.
>
> Step 3.11 is a step that is not technically part of the documentation
> process at all, since it only applies to one family of GnuCash’s supported
> operating systems. Mac and Windows writers don’t perform this step, and the
> fact that I have been contributing changes for years without conducting
> these tests underscores the fact that they aren’t a required part of the
> Documentation Update process.
>
> Steps 3.12 and following are back to steps taken on each change—although at
> this point, I wonder whether people are preparing patches and attaching
> them to Bugzilla bugs (steps 3.15-3.17), or whether everyone has moved to
> the Github pull request method.
>

I believe you make a valid point. The current structure makes it more
difficult than necessary to find what you should do next while working on
documentation. IMO would make more sense to have a section "prepare your
environment" with the details of one time actions and a section on what's
needed the handle one specific bug. Optionally a section on how to clean up if
things went wrong or when switching to another bug to work on.

I didn't follow the discussion in the past in detail I'm afraid so I don't
know why this or something similar wasn't taken into consideration.

Geert
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

doncram
Wow the process to change documentation (at
http://wiki.gnucash.org/wiki/Documentation_Update_Instructions ) seems
pretty complicated, even impossible for Windows users.  I would hope it
should be possible to have a full working version of the Tutorial and
Concepts Guide that is open for edits/improvement by users informed about
accounting and trying to make the Guide more useful for basic users, in a
wiki document (where changes can be seen and there can be discussion at
Talk pages).  Then periodically when the Wiki editors get consensus that a
new version is ready, just one programmer type person with Linux could go
through those complicated steps to get it published.  Allow different
parties to specialize in how they contribute.  I for one would like to
contribute in improving the Concepts guide text.

Specifically I would like to go through Chapter 13: Business Features and
streamline it.  One change would be to move and revise the confusing-to-me
"Setting up tax tables" section, which conceivably could be about business
income taxes or other taxes, but is not.  It might be introduced later,
e.g. under Invoicing, i.e. introduce as a complication only when relevant
for users who are going to be invoicing and collecting sales taxes.  I have
led classrooms of students in a computer lab through the process of each
setting up a company;  i would not want to get bogged down in those
specifics which might not apply at all for many businesses, and where the
user likely does not have all the specific info needed (specifics on sales
tax rates, applicable to what types of sales, etc.) right away.  Another
example for the future would be to give instructions on how to adopt one of
a few standard charts of accounts.

I am not sure if I can just work on the Chapter 13 text somewhere public
and involve others in reviewing and improving it. The Wiki page for
"Concept Guide" at http://wiki.gnucash.org/wiki/Concept_Guide is not a
version of the guide to be edited, nor does it link to one in any obvious
way.  I would certainly like to try following the Documentation Update
Instructions together with other new contributors here and participate in
improving it.

Currently I am trying to log into the Wiki but keep getting error message:
There seems to be a problem with your login session; this action has been
canceled as a precaution against session hijacking. Go back to the previous
page, reload that page and then try again.
Recent changes shows that Jrall opened an account for me, which I reported
did not allow me to edit, because I need to get some user group rights
added, and I don't yet know if I was able to log in again whether I would
be able to edit yet.

cheers, Doncram

On Wed, May 3, 2017 at 11:10 AM, Geert Janssens <[hidden email]>
wrote:

> On dinsdag 2 mei 2017 18:10:35 CEST David T. via gnucash-devel wrote:
> > Here’s what I mean:
> >
> > On the Documentation Update instructions, section 3 contains 17 different
> > steps.
> >
> > Step 3.1: Create a Bugzilla Bug is a step that should be undertaken with
> > every proposed change to the documentation.
> >
> > Step 3.2: Clone the Documentation, however, is (presumably) a one-time
> > setup. Steps 3.3-3.5 similarly are one-time setups (unless you’re a
> screwup
> > like me, and then you get to do them over and over again).
> >
> > Steps 3.6-3.10 are again repeated for each change to the docs.
> >
> > Step 3.11 is a step that is not technically part of the documentation
> > process at all, since it only applies to one family of GnuCash’s
> supported
> > operating systems. Mac and Windows writers don’t perform this step, and
> the
> > fact that I have been contributing changes for years without conducting
> > these tests underscores the fact that they aren’t a required part of the
> > Documentation Update process.
> >
> > Steps 3.12 and following are back to steps taken on each change—although
> at
> > this point, I wonder whether people are preparing patches and attaching
> > them to Bugzilla bugs (steps 3.15-3.17), or whether everyone has moved to
> > the Github pull request method.
> >
>
> I believe you make a valid point. The current structure makes it more
> difficult than necessary to find what you should do next while working on
> documentation. IMO would make more sense to have a section "prepare your
> environment" with the details of one time actions and a section on what's
> needed the handle one specific bug. Optionally a section on how to clean
> up if
> things went wrong or when switching to another bug to work on.
>
> I didn't follow the discussion in the past in detail I'm afraid so I don't
> know why this or something similar wasn't taken into consideration.
>
> Geert
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

GnuCash - Dev mailing list
Hey Doncram,

Glad to hear you joining the fray. If you look through the list archives, you will see that I am another contributor who is challenged by the Documentation Update procedures (and the wiki documentation, and the fact that there is a decade-old copy of the Concept Guide on the wiki to trip up unsuspecting users…). I would love to offer you advice on these issues, but to be truthful, I have gotten things to work only incrementally, and with many errors along the way. I could perhaps show you how NOT to do this! A little more seriously, I would recommend working slowly through the Documentation update process page, and come to the list each and every time you hit a brick wall. That is ultimately what I did.

As for the wiki login issue, try clearing out your browser cookies, and see if that helps. I seem to recall needing to do that in order to gain access at one point.

David

P.S. To the GnuCash Wiki Protectorate: this is yet another person who notes the outdated and incorrect Concept Guide information available on GnuCash’s wiki. How many more are out there that we don’t know about—and why, exactly, is it still necessary to keep this crap information up on the wiki?

> On May 23, 2017, at 10:11 PM, doncram <[hidden email]> wrote:
>
> Wow the process to change documentation (at http://wiki.gnucash.org/wiki/Documentation_Update_Instructions <http://wiki.gnucash.org/wiki/Documentation_Update_Instructions> ) seems pretty complicated, even impossible for Windows users.  I would hope it should be possible to have a full working version of the Tutorial and Concepts Guide that is open for edits/improvement by users informed about accounting and trying to make the Guide more useful for basic users, in a wiki document (where changes can be seen and there can be discussion at Talk pages).  Then periodically when the Wiki editors get consensus that a new version is ready, just one programmer type person with Linux could go through those complicated steps to get it published.  Allow different parties to specialize in how they contribute.  I for one would like to contribute in improving the Concepts guide text.  
>
> Specifically I would like to go through Chapter 13: Business Features and streamline it.  One change would be to move and revise the confusing-to-me "Setting up tax tables" section, which conceivably could be about business income taxes or other taxes, but is not.  It might be introduced later, e.g. under Invoicing, i.e. introduce as a complication only when relevant for users who are going to be invoicing and collecting sales taxes.  I have led classrooms of students in a computer lab through the process of each setting up a company;  i would not want to get bogged down in those specifics which might not apply at all for many businesses, and where the user likely does not have all the specific info needed (specifics on sales tax rates, applicable to what types of sales, etc.) right away.  Another example for the future would be to give instructions on how to adopt one of a few standard charts of accounts.
>
> I am not sure if I can just work on the Chapter 13 text somewhere public and involve others in reviewing and improving it. The Wiki page for "Concept Guide" at http://wiki.gnucash.org/wiki/Concept_Guide <http://wiki.gnucash.org/wiki/Concept_Guide> is not a version of the guide to be edited, nor does it link to one in any obvious way.  I would certainly like to try following the Documentation Update Instructions together with other new contributors here and participate in improving it.  
>
> Currently I am trying to log into the Wiki but keep getting error message:
> There seems to be a problem with your login session; this action has been canceled as a precaution against session hijacking. Go back to the previous page, reload that page and then try again.
> Recent changes shows that Jrall opened an account for me, which I reported did not allow me to edit, because I need to get some user group rights added, and I don't yet know if I was able to log in again whether I would be able to edit yet.
>
> cheers, Doncram
>
> On Wed, May 3, 2017 at 11:10 AM, Geert Janssens <[hidden email] <mailto:[hidden email]>> wrote:
> On dinsdag 2 mei 2017 18:10:35 CEST David T. via gnucash-devel wrote:
> > Here’s what I mean:
> >
> > On the Documentation Update instructions, section 3 contains 17 different
> > steps.
> >
> > Step 3.1: Create a Bugzilla Bug is a step that should be undertaken with
> > every proposed change to the documentation.
> >
> > Step 3.2: Clone the Documentation, however, is (presumably) a one-time
> > setup. Steps 3.3-3.5 similarly are one-time setups (unless you’re a screwup
> > like me, and then you get to do them over and over again).
> >
> > Steps 3.6-3.10 are again repeated for each change to the docs.
> >
> > Step 3.11 is a step that is not technically part of the documentation
> > process at all, since it only applies to one family of GnuCash’s supported
> > operating systems. Mac and Windows writers don’t perform this step, and the
> > fact that I have been contributing changes for years without conducting
> > these tests underscores the fact that they aren’t a required part of the
> > Documentation Update process.
> >
> > Steps 3.12 and following are back to steps taken on each change—although at
> > this point, I wonder whether people are preparing patches and attaching
> > them to Bugzilla bugs (steps 3.15-3.17), or whether everyone has moved to
> > the Github pull request method.
> >
>
> I believe you make a valid point. The current structure makes it more
> difficult than necessary to find what you should do next while working on
> documentation. IMO would make more sense to have a section "prepare your
> environment" with the details of one time actions and a section on what's
> needed the handle one specific bug. Optionally a section on how to clean up if
> things went wrong or when switching to another bug to work on.
>
> I didn't follow the discussion in the past in detail I'm afraid so I don't
> know why this or something similar wasn't taken into consideration.
>
> Geert
> _______________________________________________
> gnucash-devel mailing list
> [hidden email] <mailto:[hidden email]>
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel <https://lists.gnucash.org/mailman/listinfo/gnucash-devel>
>

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Adonay Felipe Nogueira
In reply to this post by doncram
Personally, I think this would be mostly solved by switching to TeXInfo,
or to Org Mode. The latter also supports TeXInfo publication.

--
- [[https://libreplanet.org/wiki/User:Adfeno]]
- Palestrante e consultor sobre /software/ livre (não confundir com
  gratis).
- "WhatsApp"? Ele não é livre, por isso não uso. Iguais a ele prefiro
  GNU Ring, ou Tox. Quer outras formas de contato? Adicione o vCard
  que está no endereço acima aos teus contatos.
- Pretende me enviar arquivos .doc, .ppt, .cdr, ou .mp3? OK, eu
  aceito, mas não repasso. Entrego apenas em formatos favoráveis ao
  /software/ livre. Favor entrar em contato em caso de dúvida.
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Derek Atkins-3
In reply to this post by doncram
Hi,

On Tue, May 23, 2017 1:11 pm, doncram wrote:
> Wow the process to change documentation (at
> http://wiki.gnucash.org/wiki/Documentation_Update_Instructions ) seems
> pretty complicated, even impossible for Windows users.

What's so complicated about a git checkout and using the appropriate
DocBook tools to edit the DocBook sources of the manual?

>   I would hope it
> should be possible to have a full working version of the Tutorial and
> Concepts Guide that is open for edits/improvement by users informed about
> accounting and trying to make the Guide more useful for basic users, in a
> wiki document (where changes can be seen and there can be discussion at
> Talk pages).

There's no good way to translate from Wiki to PDF.  There was a conscious
decsion a while ago that we wanted offline help, which meant a non-wiki
form.

>    Then periodically when the Wiki editors get consensus that a
> new version is ready, just one programmer type person with Linux could go
> through those complicated steps to get it published.  Allow different
> parties to specialize in how they contribute.  I for one would like to
> contribute in improving the Concepts guide text.

The publication side is fine, and we do already go through that.  As for
people reading/editing -- github pull requests provide that.

[snip]
> Currently I am trying to log into the Wiki but keep getting error message:
> There seems to be a problem with your login session; this action has been
> canceled as a precaution against session hijacking. Go back to the
> previous
> page, reload that page and then try again.

I think you need to clear your cache/cookies and try again.  Not sure what
happened here.

> Recent changes shows that Jrall opened an account for me, which I reported
> did not allow me to edit, because I need to get some user group rights
> added, and I don't yet know if I was able to log in again whether I would
> be able to edit yet.

This is correct; you have not validated your email.  At least according to
the database, you are not "email authenticated" which is a requirement to
edit the wiki.  I do not know why it says "email_authenticated" is NULL
for both you and Buddha.  Did you actually confirm your email?  Can you
try confirming it again?

The previous users in the list appear to have done so -- but it also
appears there are a number of users who have not.

This COULD be a bug in the ConfirmAccount plugin where it does not
properly translate the email authentication across.  Or it could be a bad
interaction between CA and the built-in email confirmation.

So can you confirm you confirmed your email?  Can you try confirming
again?  Let me know if/when you attempt this.  Better yet, can you come
onto IRC during 9a-5p EDT and we can work on trying to track down the
issue.

Yes, I could just go into the database and fix it manually (which I'll
gladly do as a last resort), but I'd rather get down to the bottom of the
actual issue.

Thanks,

-derek

--
       Derek Atkins                 617-623-3745
       [hidden email]             www.ihtfp.com
       Computer and Internet Security Consultant

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

doncram
Thanks for replies.  I had previously confirmed my email, but I tried again
now and it works, and I made a first edit at the page named "Concept Guide"
to clarify that the page is to be about development of the GnuCash Tutorial
and Concept Guide.  I also revised the Introduction and set up a section
for a new review, as of May 2017, of the Guide.

Great, maybe we have several new and old Wiki users who may work together
for a bit to improve this Wiki, which in turn should advance the GnuCash
project. :)  Right, the Documentation Update Instructions are not really
that complicated, although they do state directly to me that "It is
probably possible but complicated to update the documentation in Windows",
which is where I am at.  In the past I used LaTeX and TeX in a Unix
environment and could find my way to install Linux and do all the rest, but
I would like to specialize where I can contribute most directly.  I can
understand that the actual Guide can't be generated from Wiki pages;  the
Guide exists in XML files which are what are to actually be edited.  But it
seems to me that editing XML files and testing the documentation would be
about rolling out an approved new version of the Guide. The instructions
don't cover the probably informal process of sharing text files of the
intended wording. All will become clear, I expect, when I first work on
updating some specific section of the Guide. :)

Right now, I'd like to create a Wiki page about getting started in the
GnuCash Wiki.  I personally am very experienced in editing Wikipedia and
think I might be able to help the few others who are new to editing in the
Wiki right now.  For example, this page would explain the concept of user
rights and link to the page about user groups (
http://wiki.gnucash.org/wiki/Special:ListGroupRights), as in the following:
*... At the most basic level as a new user, you can't edit but you can have
a watchlist, which is something more than readers who don't have accounts.
To be able to edit, you need to be a member of the emailconfirmed group.
To get that, click on "Preferences", see your "User profile", and select
the option to confirm your email, which sends an email to your personal
email account.  In your personal email software, find that email and click
on the link it provides.  You may or may need to log out and log back in
again.  Under Preferences, you should see your membership in
"emailconfirmed" group.  At the main GnuCash page, there is nothing
different...you still can't edit there, because it is protected for editing
only by some other group.  At many other pages, you can now edit.*
I would be happy to develop such a page and corresponding Discussion page.
I would include a section with links and some discussion for new users who
are already are Wikipedia editors.  Could someone please create a page for
that, or, better, could I please be given "Autoconfirmed" status, so I
could do that?  :)  Of course I recognize that anything and everything I
edit could be rolled back, if it doesn't fit in.  Without "Autopatrolled"
status, any edits I make will be marked for others to patrol / review, and
I have no problem with finding out that some edits are reversed...I would
expect to discuss at Talk pages and learn from the process.

cheers, Doncram

On Tue, May 23, 2017 at 4:22 PM, Derek Atkins <[hidden email]> wrote:

> Hi,
>
> On Tue, May 23, 2017 1:11 pm, doncram wrote:
> > Wow the process to change documentation (at
> > http://wiki.gnucash.org/wiki/Documentation_Update_Instructions ) seems
> > pretty complicated, even impossible for Windows users.
>
> What's so complicated about a git checkout and using the appropriate
> DocBook tools to edit the DocBook sources of the manual?
>
> >   I would hope it
> > should be possible to have a full working version of the Tutorial and
> > Concepts Guide that is open for edits/improvement by users informed about
> > accounting and trying to make the Guide more useful for basic users, in a
> > wiki document (where changes can be seen and there can be discussion at
> > Talk pages).
>
> There's no good way to translate from Wiki to PDF.  There was a conscious
> decsion a while ago that we wanted offline help, which meant a non-wiki
> form.
>
> >    Then periodically when the Wiki editors get consensus that a
> > new version is ready, just one programmer type person with Linux could go
> > through those complicated steps to get it published.  Allow different
> > parties to specialize in how they contribute.  I for one would like to
> > contribute in improving the Concepts guide text.
>
> The publication side is fine, and we do already go through that.  As for
> people reading/editing -- github pull requests provide that.
>
> [snip]
> > Currently I am trying to log into the Wiki but keep getting error
> message:
> > There seems to be a problem with your login session; this action has been
> > canceled as a precaution against session hijacking. Go back to the
> > previous
> > page, reload that page and then try again.
>
> I think you need to clear your cache/cookies and try again.  Not sure what
> happened here.
>
> > Recent changes shows that Jrall opened an account for me, which I
> reported
> > did not allow me to edit, because I need to get some user group rights
> > added, and I don't yet know if I was able to log in again whether I would
> > be able to edit yet.
>
> This is correct; you have not validated your email.  At least according to
> the database, you are not "email authenticated" which is a requirement to
> edit the wiki.  I do not know why it says "email_authenticated" is NULL
> for both you and Buddha.  Did you actually confirm your email?  Can you
> try confirming it again?
>
> The previous users in the list appear to have done so -- but it also
> appears there are a number of users who have not.
>
> This COULD be a bug in the ConfirmAccount plugin where it does not
> properly translate the email authentication across.  Or it could be a bad
> interaction between CA and the built-in email confirmation.
>
> So can you confirm you confirmed your email?  Can you try confirming
> again?  Let me know if/when you attempt this.  Better yet, can you come
> onto IRC during 9a-5p EDT and we can work on trying to track down the
> issue.
>
> Yes, I could just go into the database and fix it manually (which I'll
> gladly do as a last resort), but I'd rather get down to the bottom of the
> actual issue.
>
> Thanks,
>
> -derek
>
> --
>        Derek Atkins                 617-623-3745
>        [hidden email]             www.ihtfp.com
>        Computer and Internet Security Consultant
>
>
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Adrien Monteleone
In reply to this post by Derek Atkins-3

> On May 23, 2017, at 3:22 PM, Derek Atkins <[hidden email]> wrote:
>
> Hi,
>
> On Tue, May 23, 2017 1:11 pm, doncram wrote:
>> Wow the process to change documentation (at
>> http://wiki.gnucash.org/wiki/Documentation_Update_Instructions ) seems
>> pretty complicated, even impossible for Windows users.
>
> What's so complicated about a git checkout and using the appropriate
> DocBook tools to edit the DocBook sources of the manual?
>
>>  I would hope it
>> should be possible to have a full working version of the Tutorial and
>> Concepts Guide that is open for edits/improvement by users informed about
>> accounting and trying to make the Guide more useful for basic users, in a
>> wiki document (where changes can be seen and there can be discussion at
>> Talk pages).
>
> There's no good way to translate from Wiki to PDF.  There was a conscious
> decsion a while ago that we wanted offline help, which meant a non-wiki
> form.

I’m certainly no expert on the matter and I have no beef with the GIT process for documentation, but that seems odd at first glance since wikis are markdown inside HTML which is a subset of XML which the doc procedures turn into PDF. Or did I misunderstand something?

-Adrien

>
>>   Then periodically when the Wiki editors get consensus that a
>> new version is ready, just one programmer type person with Linux could go
>> through those complicated steps to get it published.  Allow different
>> parties to specialize in how they contribute.  I for one would like to
>> contribute in improving the Concepts guide text.
>
> The publication side is fine, and we do already go through that.  As for
> people reading/editing -- github pull requests provide that.
>
> [snip]
>> Currently I am trying to log into the Wiki but keep getting error message:
>> There seems to be a problem with your login session; this action has been
>> canceled as a precaution against session hijacking. Go back to the
>> previous
>> page, reload that page and then try again.
>
> I think you need to clear your cache/cookies and try again.  Not sure what
> happened here.
>
>> Recent changes shows that Jrall opened an account for me, which I reported
>> did not allow me to edit, because I need to get some user group rights
>> added, and I don't yet know if I was able to log in again whether I would
>> be able to edit yet.
>
> This is correct; you have not validated your email.  At least according to
> the database, you are not "email authenticated" which is a requirement to
> edit the wiki.  I do not know why it says "email_authenticated" is NULL
> for both you and Buddha.  Did you actually confirm your email?  Can you
> try confirming it again?
>
> The previous users in the list appear to have done so -- but it also
> appears there are a number of users who have not.
>
> This COULD be a bug in the ConfirmAccount plugin where it does not
> properly translate the email authentication across.  Or it could be a bad
> interaction between CA and the built-in email confirmation.
>
> So can you confirm you confirmed your email?  Can you try confirming
> again?  Let me know if/when you attempt this.  Better yet, can you come
> onto IRC during 9a-5p EDT and we can work on trying to track down the
> issue.
>
> Yes, I could just go into the database and fix it manually (which I'll
> gladly do as a last resort), but I'd rather get down to the bottom of the
> actual issue.
>
> Thanks,
>
> -derek
>
> --
>       Derek Atkins                 617-623-3745
>       [hidden email]             www.ihtfp.com
>       Computer and Internet Security Consultant
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Adrien Monteleone

> On May 23, 2017, at 8:50 PM, Adrien Monteleone <[hidden email]> wrote:
>
>>
>> On May 23, 2017, at 3:22 PM, Derek Atkins <[hidden email]> wrote:
>>
>> Hi,
>>
>> On Tue, May 23, 2017 1:11 pm, doncram wrote:
>>> Wow the process to change documentation (at
>>> http://wiki.gnucash.org/wiki/Documentation_Update_Instructions ) seems
>>> pretty complicated, even impossible for Windows users.
>>
>> What's so complicated about a git checkout and using the appropriate
>> DocBook tools to edit the DocBook sources of the manual?
>>
>>> I would hope it
>>> should be possible to have a full working version of the Tutorial and
>>> Concepts Guide that is open for edits/improvement by users informed about
>>> accounting and trying to make the Guide more useful for basic users, in a
>>> wiki document (where changes can be seen and there can be discussion at
>>> Talk pages).
>>
>> There's no good way to translate from Wiki to PDF.  There was a conscious
>> decsion a while ago that we wanted offline help, which meant a non-wiki
>> form.
>
> I’m certainly no expert on the matter and I have no beef with the GIT process for documentation, but that seems odd at first glance since wikis are markdown inside HTML which is a subset of XML which the doc procedures turn into PDF. Or did I misunderstand something?
>
> -Adrien

On that note, I already knew about html2pdf for *nix, but even better - there’s this: Extension:Pdf_Export on the mediawiki site.

-Adrien

>>
>>>  Then periodically when the Wiki editors get consensus that a
>>> new version is ready, just one programmer type person with Linux could go
>>> through those complicated steps to get it published.  Allow different
>>> parties to specialize in how they contribute.  I for one would like to
>>> contribute in improving the Concepts guide text.
>>
>> The publication side is fine, and we do already go through that.  As for
>> people reading/editing -- github pull requests provide that.
>>
>> [snip]
>>> Currently I am trying to log into the Wiki but keep getting error message:
>>> There seems to be a problem with your login session; this action has been
>>> canceled as a precaution against session hijacking. Go back to the
>>> previous
>>> page, reload that page and then try again.
>>
>> I think you need to clear your cache/cookies and try again.  Not sure what
>> happened here.
>>
>>> Recent changes shows that Jrall opened an account for me, which I reported
>>> did not allow me to edit, because I need to get some user group rights
>>> added, and I don't yet know if I was able to log in again whether I would
>>> be able to edit yet.
>>
>> This is correct; you have not validated your email.  At least according to
>> the database, you are not "email authenticated" which is a requirement to
>> edit the wiki.  I do not know why it says "email_authenticated" is NULL
>> for both you and Buddha.  Did you actually confirm your email?  Can you
>> try confirming it again?
>>
>> The previous users in the list appear to have done so -- but it also
>> appears there are a number of users who have not.
>>
>> This COULD be a bug in the ConfirmAccount plugin where it does not
>> properly translate the email authentication across.  Or it could be a bad
>> interaction between CA and the built-in email confirmation.
>>
>> So can you confirm you confirmed your email?  Can you try confirming
>> again?  Let me know if/when you attempt this.  Better yet, can you come
>> onto IRC during 9a-5p EDT and we can work on trying to track down the
>> issue.
>>
>> Yes, I could just go into the database and fix it manually (which I'll
>> gladly do as a last resort), but I'd rather get down to the bottom of the
>> actual issue.
>>
>> Thanks,
>>
>> -derek
>>
>> --
>>      Derek Atkins                 617-623-3745
>>      [hidden email]             www.ihtfp.com
>>      Computer and Internet Security Consultant
>>
>> _______________________________________________
>> gnucash-devel mailing list
>> [hidden email]
>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Some Assistance Please

Michael Ferrara-2
In reply to this post by Adrien Monteleone
There's no good way to translate from Wiki to PDF


Really? PDF can handle hard links within a document. Reference books with
linearly organized chapters and cross-references have been around since
before the Bible. Understandably, the wiki is spineless and completely
semantic in the way its pages are accessed, nevertheless last time I
checked it still had a title page and a table of its contents.  It sounds
like all we need is someone to take on the role of an Editor. C'mon! You
will get 'mad street cred' on the information superhighway.

I totally understand that such a linear book goes against the ideals of
unmanaged distributed open source authoring, but the wiki does seriously
need a band-aid.  Uh, just include a LaTeX-like tag to give each wiki page
out there a priority and write or find a simple script to pull it all
together for printing or kindling or whatever.

I am not a pro-programmer but I read a lot of books in college, virtual and
tangible.
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
12