From mboxrd@z Thu Jan 1 00:00:00 1970 From: John Hendy Subject: Re: Clarification on ChangeLog documentation Date: Sat, 15 Mar 2014 10:17:17 -0500 Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:44553) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOqKt-0006uA-FS for emacs-orgmode@gnu.org; Sat, 15 Mar 2014 11:17:20 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WOqKr-0002Hs-Vz for emacs-orgmode@gnu.org; Sat, 15 Mar 2014 11:17:19 -0400 Received: from mail-ob0-x22d.google.com ([2607:f8b0:4003:c01::22d]:65089) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOqKr-0002Hf-OT for emacs-orgmode@gnu.org; Sat, 15 Mar 2014 11:17:17 -0400 Received: by mail-ob0-f173.google.com with SMTP id gq1so3808543obb.4 for ; Sat, 15 Mar 2014 08:17:17 -0700 (PDT) In-Reply-To: List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode Hi Bastien, Thanks for the changes; comments below: On Fri, Mar 14, 2014 at 11:09 AM, John Hendy 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 > > >>