From: John Hendy <jw.hendy@gmail.com>
To: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: Clarification on ChangeLog documentation
Date: Sat, 15 Mar 2014 10:17:17 -0500 [thread overview]
Message-ID: <CA+M2ft-f91o5ke2i8en6ck-y91zsv8Bxfd+BcYTVzBNUxj7evA@mail.gmail.com> (raw)
In-Reply-To: <CA+M2ft9cxWtKv2xarkFzB+jmscnOS+CToyqpE6-fGTcHSV87wg@mail.gmail.com>
Hi Bastien,
Thanks for the changes; comments below:
On Fri, Mar 14, 2014 at 11:09 AM, John Hendy <jw.hendy@gmail.com> wrote:
> Greetings,
>
>
[snip]
> The specification is clear enough for lines 1 and 2.
>
> #+begin_quote
> In line 3, the ChangeLog entry should start, in a similar format as in
> the old ChangeLog files, but without the author information (which is
> part of the commit anyway).
> #+end_quote
>
> The ChangeLog instructions refer back to the "old ChangeLog" files
> ,but if you've never submitted a patch, that's not very helpful and
> there's no link to read about the "old" format. I referred to the
> example for this, but more on that below.
>
In the example provided, the first asterisk lists a file and two
changed nodes. Why is the third just parentheses with no file.
Assumption: it's also in org-timer.el, but the description of the
change just wouldn't have matched the other two.
> #+begin_quote
> Variables and functions names are quoted like =`this'= (backquote and
> single quote).
> #+end_quote
>
> Does the Org verbatim markup help explain this any better than just
> using, `this'? It's not fontified, so to an Org-novice, it might not
> be clear why == surround the word.
>
Thanks for changing!
> And, walking through the example line by line:
>
> #+begin_quote
> Capture: Fix the case of using a template file
> #+end_quote
>
> What determines what should come before the colon? Obviously the
> example was to capture functionality and the corresponding
> documentation, but is there a set list of words that should be used? A
> recent patch, for example, clarified that the :exports header argument
> only applied to code blocks, not inline code. I used:
>
> Header arguments: blah blah blah
>
> Should that have been a manual section title, something specifically
> about exporting, code blocks, babel... other?
>
> I understand the first line should contain the file name. Is this
> correct, as it's not in the manual example. And should it be file.ext,
> or dir/file.ext for the first line summary?
>
Clarified now. file-name: blah blah.
> #+begin_quote:
> * lisp/org-capture.el (org-capture-set-plist): Make sure txt is a
> string before calling `string-match'.
> (org-capture-templates): Fix customization type.
>
> * doc/org.texi (Capture): Document using a file for a template.
> #+end_quote
>
> My change modified only org.texi, but in two places. Do I need a
> "header" per change, or just a header per file? Nevermind; Bastien
> responded to my submission so I now know the answer is one header,
> with two content bits. Also, from his response, I gather that the bit
> in between parentheses should be the @node name of the section being
> changed, correct?
>
I think this is now resolved for me as well.
> #+begin_quote:
> The problem here was that a wrong keyword was given in the
> customization type. This let to a string-match against a list value.
> #+end_quote
>
> I couldn't tell if this paragraph was supposed to be a continuation of
> the second "header" above, or if it was it's own standalone summary of
> the gist of both changes.
>
Taking this to be general elaboration about /both/ changes; i.e. a
summary of the motivation of the changes in general.
> #+begin_quote
> Modified from a patch proposal by Johan Friis.
> #+end_quote
>
> Can I reference mailing list threads, or is this not advised? Or
> should I be mentioning the person who responded on the mailing list
> for the clarification which led to the documentation modification?
>
Still not sure about this.
> #+begin_quote
> TINYCHANGE
> #+end_quote
>
> Is the FSF requirement necessary only if one commit > x lines, or is
> it cumulative?
>
Also not sure about this, but I've seen enough FSF forms asked for
that I assume I'll be asked if I hit whatever the limit is.
> I can take a shot at clarifying this in the manual example based on
> responses to the above, if desired. I'm just getting up to speed, so
> perhaps it's just me that's ignorant on the process :)
Thanks for adding the new info!
John
>
>
> Best regards,
> John
>
>
>>
next prev parent reply other threads:[~2014-03-15 15:17 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-03-14 16:09 Clarification on ChangeLog documentation John Hendy
2014-03-15 6:28 ` Bastien
2014-03-15 15:17 ` John Hendy [this message]
2014-03-17 1:08 ` Bastien
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CA+M2ft-f91o5ke2i8en6ck-y91zsv8Bxfd+BcYTVzBNUxj7evA@mail.gmail.com \
--to=jw.hendy@gmail.com \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).