Re: [PATCH] Documentation: add a README file
Yann Droneaud ydrone...@opteya.com writes: The documentation is in AsciiDoc format: it should be written somewhere with links to AsciiDoc documentation so that it became easy to find how to write documentation for Git. Certainly this does not deserve a *new* file to hold it. Isn't this inferrable from the top-level INSTALL already? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: add a README file
Le 21.03.2013 16:31, Junio C Hamano a écrit : Yann Droneaud ydrone...@opteya.com writes: The documentation is in AsciiDoc format: it should be written somewhere with links to AsciiDoc documentation so that it became easy to find how to write documentation for Git. Certainly this does not deserve a *new* file to hold it. That's the first one I look for. There were no indication about how to write documentation in SubmittingPatches. Later, I've found the only useful piece of advice regarding the documentation in howto/new-command.txt: What every extension command needs -- You must have a man page, written in asciidoc (this is what Git help followed by your subcommand name will display). Be aware that there is a local asciidoc configuration and macros which you should use. It's often helpful to start by cloning an existing page and replacing the text content. And I was grep'ing for ascii[ _-]doc throughout the sources ! Isn't this inferrable from the top-level INSTALL already? In short: No. You want me to look in the INSTALL file to search for the syntax to write documentation ? For someone who don't follow Git development, it's really not the file you're looking for. Regards. -- Yann Droneaud OPTEYA -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: add a README file
Yann Droneaud ydrone...@opteya.com writes: There were no indication about how to write documentation in SubmittingPatches. I would agree that is probably the right place for it if we were to add insns/hints. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: add a README file
Junio C Hamano gits...@pobox.com writes: Yann Droneaud ydrone...@opteya.com writes: There were no indication about how to write documentation in SubmittingPatches. I would agree that is probably the right place for it if we were to add insns/hints. I take it back. SubmittingPatches does not, and I do not think it should, discuss any issue that is programming language specific. We already have a dedicated section for documentation updates in CodingGuidelines, though. Documentation/CodingGuidelines | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b1bfff6..7e4d571 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -237,6 +237,9 @@ For Python scripts: Writing Documentation: + Most (if not all) of the documentation pages are written in AsciiDoc + and processed into HTML output and manpages. + Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions. A few commented examples follow to provide reference -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: add a README file
Le jeudi 21 mars 2013 à 10:39 -0700, Junio C Hamano a écrit : Yann Droneaud ydrone...@opteya.com writes: There were no indication about how to write documentation in SubmittingPatches. I would agree that is probably the right place for it if we were to add insns/hints. But it will be difficult to find the place to put a note about how to write the documentation. Anyway, having a README at the Documentation/ level could also help to explain what to be found in this directory: - user-manual - howto - technical - RelNote - SubmittingPatches - CodingGuidelines - etc. Regards. -- Yann Droneaud OPTEYA -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: add a README file
Hi, Le jeudi 21 mars 2013 à 14:16 -0700, Junio C Hamano a écrit : diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b1bfff6..7e4d571 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -237,6 +237,9 @@ For Python scripts: Writing Documentation: + Most (if not all) of the documentation pages are written in AsciiDoc + and processed into HTML output and manpages. + Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions. A few commented examples follow to provide reference Nice, I'm OK with this change. (But still thinking a README would be useful *too*). Regards. -- Yann Droneaud OPTEYA -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Documentation: add a README file
Yann Droneaud wrote: Anyway, having a README at the Documentation/ level could also help to explain what to be found in this directory: - user-manual - howto - technical - RelNote - SubmittingPatches - CodingGuidelines - etc. A Documentation/README or Documentation/INDEX in the spirit of Linux's Documentation/00-INDEX could be interesting if it does not bitrot (unlike Linux's 00-INDEX). Presumably that means it would have to be pretty brief. Thanks, Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html