# [PATCH] Documentation: add a README file 8 messages from 2013-03-21 to 2013-03-21. Participants: Yann Droneaud, Junio C Hamano, Jonathan Nieder. Thread: https://gitlist.dev/t/33248 ## Yann Droneaud, 2013-03-21 13:45 Subject: [PATCH] Documentation: add a README file Message-ID: <1363873555-8274-1-git-send-email-ydroneaud@opteya.com> URL: https://gitlist.dev/e/1363873555-8274-1-git-send-email-ydroneaud%40opteya.com ``` 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. Signed-off-by: Yann Droneaud --- Documentation/README | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 Documentation/README diff --git a/Documentation/README b/Documentation/README new file mode 100644 index 0000000..c41734c --- /dev/null +++ b/Documentation/README @@ -0,0 +1,13 @@ +Documentation +============= + +Most of the Git documentation is in AsciiDoc format, +a lightweight markup text language. + +AsciiDoc formatted files can be translated to man pages, +HTML, DocBook or PDF documents. + +See: +- http://asciidoc.org/ +- https://git.wiki.kernel.org/index.php/AsciiDoc + -- 1.7.11.7 ``` ## Junio C Hamano, 2013-03-21 15:31 Subject: Re: [PATCH] Documentation: add a README file Message-ID: <7v8v5gbwh6.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7v8v5gbwh6.fsf%40alter.siamese.dyndns.org In-Reply-To: <1363873555-8274-1-git-send-email-ydroneaud@opteya.com> ``` Yann Droneaud 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? ``` ## Yann Droneaud, 2013-03-21 15:49 Subject: Re: [PATCH] Documentation: add a README file Message-ID: <64e67681cf5584b51bc84082fe6304c0@meuh.org> URL: https://gitlist.dev/e/64e67681cf5584b51bc84082fe6304c0%40meuh.org In-Reply-To: <7v8v5gbwh6.fsf@alter.siamese.dyndns.org> ``` Le 21.03.2013 16:31, Junio C Hamano a écrit : > Yann Droneaud 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 ``` ## Junio C Hamano, 2013-03-21 17:39 Subject: Re: [PATCH] Documentation: add a README file Message-ID: <7vzjxwabzv.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vzjxwabzv.fsf%40alter.siamese.dyndns.org In-Reply-To: <64e67681cf5584b51bc84082fe6304c0@meuh.org> ``` Yann Droneaud 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. ``` ## Junio C Hamano, 2013-03-21 21:16 Subject: Re: [PATCH] Documentation: add a README file Message-ID: <7v620ka1y8.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7v620ka1y8.fsf%40alter.siamese.dyndns.org In-Reply-To: <7vzjxwabzv.fsf@alter.siamese.dyndns.org> ``` Junio C Hamano writes: > Yann Droneaud 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 ``` ## Yann Droneaud, 2013-03-21 21:59 Subject: Re: [PATCH] Documentation: add a README file Message-ID: <1363903193.6289.57.camel@test.quest-ce.net> URL: https://gitlist.dev/e/1363903193.6289.57.camel%40test.quest-ce.net In-Reply-To: <7vzjxwabzv.fsf@alter.siamese.dyndns.org> ``` Le jeudi 21 mars 2013 à 10:39 -0700, Junio C Hamano a écrit : > Yann Droneaud 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 ``` ## Yann Droneaud, 2013-03-21 22:02 Subject: Re: [PATCH] Documentation: add a README file Message-ID: <1363903330.6289.59.camel@test.quest-ce.net> URL: https://gitlist.dev/e/1363903330.6289.59.camel%40test.quest-ce.net In-Reply-To: <7v620ka1y8.fsf@alter.siamese.dyndns.org> ``` 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 ``` ## Jonathan Nieder, 2013-03-21 22:09 Subject: Re: [PATCH] Documentation: add a README file Message-ID: <20130321220906.GB12223@google.com> URL: https://gitlist.dev/e/20130321220906.GB12223%40google.com In-Reply-To: <1363903193.6289.57.camel@test.quest-ce.net> ``` 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 ```