{"thread":{"id":"33248","subject":"[PATCH] Documentation: add a README file","startedAt":"2013-03-21T13:45:55Z","lastAt":"2013-03-21T22:09:06Z","messageCount":8,"participants":["Yann Droneaud","Junio C Hamano","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"211867","messageId":"1363873555-8274-1-git-send-email-ydroneaud@opteya.com","threadId":"33248","inReplyTo":null,"subject":"[PATCH] Documentation: add a README file","fromName":"Yann Droneaud","fromEmail":"ydroneaud@opteya.com","sentAt":"2013-03-21T13:45:55Z","receivedAt":"2013-03-21T13:45:55Z","isPatch":true,"sender":{"key":"ydroneaud@opteya.com","avatar":"https://avatars.githubusercontent.com/u/881377?v=4"},"body":"The documentation is in AsciiDoc format: it should be written somewhere\nwith links to AsciiDoc documentation so that it became easy to find\nhow to write documentation for Git.\n\nSigned-off-by: Yann Droneaud \n---\n Documentation/README | 13 +++++++++++++\n 1 file changed, 13 insertions(+)\n create mode 100644 Documentation/README\n\ndiff --git a/Documentation/README b/Documentation/README\nnew file mode 100644\nindex 0000000..c41734c\n--- /dev/null\n+++ b/Documentation/README\n@@ -0,0 +1,13 @@\n+Documentation\n+=============\n+\n+Most of the Git documentation is in AsciiDoc format,\n+a lightweight markup text language.\n+\n+AsciiDoc formatted files can be translated to man pages,\n+HTML, DocBook or PDF documents.\n+\n+See:\n+- http://asciidoc.org/\n+- https://git.wiki.kernel.org/index.php/AsciiDoc\n+\n-- \n1.7.11.7\n"},{"id":"211875","messageId":"7v8v5gbwh6.fsf@alter.siamese.dyndns.org","threadId":"33248","inReplyTo":"1363873555-8274-1-git-send-email-ydroneaud@opteya.com","subject":"Re: [PATCH] Documentation: add a README file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-21T15:31:33Z","receivedAt":"2013-03-21T15:31:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Yann Droneaud writes:\n\n> The documentation is in AsciiDoc format: it should be written somewhere\n> with links to AsciiDoc documentation so that it became easy to find\n> how to write documentation for Git.\n\nCertainly this does not deserve a *new* file to hold it.\nIsn't this inferrable from the top-level INSTALL already?\n"},{"id":"211880","messageId":"64e67681cf5584b51bc84082fe6304c0@meuh.org","threadId":"33248","inReplyTo":"7v8v5gbwh6.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: add a README file","fromName":"Yann Droneaud","fromEmail":"ydroneaud@opteya.com","sentAt":"2013-03-21T15:49:47Z","receivedAt":"2013-03-21T15:49:47Z","isPatch":true,"sender":{"key":"ydroneaud@opteya.com","avatar":"https://avatars.githubusercontent.com/u/881377?v=4"},"body":"Le 21.03.2013 16:31, Junio C Hamano a écrit :\n> Yann Droneaud writes:\n>\n>> The documentation is in AsciiDoc format: it should be written \n>> somewhere\n>> with links to AsciiDoc documentation so that it became easy to find\n>> how to write documentation for Git.\n>\n> Certainly this does not deserve a *new* file to hold it.\n\nThat's the first one I look for.\n\nThere were no indication about how to write documentation\nin SubmittingPatches.\n\nLater, I've found the only useful piece of advice regarding the \ndocumentation\nin howto/new-command.txt:\n\n\"\nWhat every extension command needs\n----------------------------------\n\nYou must have a man page, written in asciidoc (this is what Git help\nfollowed by your subcommand name will display). Be aware that there is\na local asciidoc configuration and macros which you should use. It's\noften helpful to start by cloning an existing page and replacing the\ntext content.\n\"\n\nAnd I was grep'ing for ascii[ _-]doc throughout the sources !\n\n> Isn't this inferrable from the top-level INSTALL already?\n\nIn short: No.\n\nYou want me to look in the INSTALL file to search for the syntax\nto write documentation ?\n\nFor someone who don't follow Git development, it's really not the file \nyou're looking for.\n\nRegards.\n\n-- \nYann Droneaud\nOPTEYA\n"},{"id":"211884","messageId":"7vzjxwabzv.fsf@alter.siamese.dyndns.org","threadId":"33248","inReplyTo":"64e67681cf5584b51bc84082fe6304c0@meuh.org","subject":"Re: [PATCH] Documentation: add a README file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-21T17:39:16Z","receivedAt":"2013-03-21T17:39:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Yann Droneaud writes:\n\n> There were no indication about how to write documentation\n> in SubmittingPatches.\n\nI would agree that is probably the right place for it if we were to\nadd insns/hints.\n"},{"id":"211902","messageId":"7v620ka1y8.fsf@alter.siamese.dyndns.org","threadId":"33248","inReplyTo":"7vzjxwabzv.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: add a README file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-21T21:16:15Z","receivedAt":"2013-03-21T21:16:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Yann Droneaud writes:\n>\n>> There were no indication about how to write documentation\n>> in SubmittingPatches.\n>\n> I would agree that is probably the right place for it if we were to\n> add insns/hints.\n\nI take it back.\n\nSubmittingPatches does not, and I do not think it should, discuss\nany issue that is programming language specific.\n\nWe already have a dedicated section for documentation updates in\nCodingGuidelines, though.\n\n Documentation/CodingGuidelines | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex b1bfff6..7e4d571 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -237,6 +237,9 @@ For Python scripts:\n \n Writing Documentation:\n \n+ Most (if not all) of the documentation pages are written in AsciiDoc\n+ and processed into HTML output and manpages.\n+\n Every user-visible change should be reflected in the documentation.\n The same general rule as for code applies -- imitate the existing\n conventions. A few commented examples follow to provide reference\n"},{"id":"211905","messageId":"1363903193.6289.57.camel@test.quest-ce.net","threadId":"33248","inReplyTo":"7vzjxwabzv.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: add a README file","fromName":"Yann Droneaud","fromEmail":"ydroneaud@opteya.com","sentAt":"2013-03-21T21:59:53Z","receivedAt":"2013-03-21T21:59:53Z","isPatch":true,"sender":{"key":"ydroneaud@opteya.com","avatar":"https://avatars.githubusercontent.com/u/881377?v=4"},"body":"Le jeudi 21 mars 2013 à 10:39 -0700, Junio C Hamano a écrit :\n> Yann Droneaud writes:\n> \n> > There were no indication about how to write documentation\n> > in SubmittingPatches.\n> \n> I would agree that is probably the right place for it if we were to\n> add insns/hints.\n> \n\nBut it will be difficult to find the place to put a note about\nhow to write the documentation.\n\nAnyway, having a README at the Documentation/ level could also help to\nexplain what to be found in this directory:\n- user-manual\n- howto\n- technical\n- RelNote\n- SubmittingPatches\n- CodingGuidelines\n- etc.\n\nRegards.\n\n-- \nYann Droneaud\nOPTEYA\n"},{"id":"211906","messageId":"1363903330.6289.59.camel@test.quest-ce.net","threadId":"33248","inReplyTo":"7v620ka1y8.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: add a README file","fromName":"Yann Droneaud","fromEmail":"ydroneaud@opteya.com","sentAt":"2013-03-21T22:02:10Z","receivedAt":"2013-03-21T22:02:10Z","isPatch":true,"sender":{"key":"ydroneaud@opteya.com","avatar":"https://avatars.githubusercontent.com/u/881377?v=4"},"body":"Hi,\n\nLe jeudi 21 mars 2013 à 14:16 -0700, Junio C Hamano a écrit :\n\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index b1bfff6..7e4d571 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -237,6 +237,9 @@ For Python scripts:\n> \n> Writing Documentation:\n> \n> + Most (if not all) of the documentation pages are written in AsciiDoc\n> + and processed into HTML output and manpages.\n> +\n> Every user-visible change should be reflected in the documentation.\n> The same general rule as for code applies -- imitate the existing\n> conventions. A few commented examples follow to provide reference\n> \n> \n\nNice, I'm OK with this change.\n(But still thinking a README would be useful *too*).\n\nRegards.\n\n-- \nYann Droneaud\nOPTEYA\n"},{"id":"211907","messageId":"20130321220906.GB12223@google.com","threadId":"33248","inReplyTo":"1363903193.6289.57.camel@test.quest-ce.net","subject":"Re: [PATCH] Documentation: add a README file","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-03-21T22:09:06Z","receivedAt":"2013-03-21T22:09:06Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Yann Droneaud wrote:\n\n> Anyway, having a README at the Documentation/ level could also help to\n> explain what to be found in this directory:\n> - user-manual\n> - howto\n> - technical\n> - RelNote\n> - SubmittingPatches\n> - CodingGuidelines\n> - etc.\n\nA Documentation/README or Documentation/INDEX in the spirit of Linux's\nDocumentation/00-INDEX could be interesting if it does not bitrot\n(unlike Linux's 00-INDEX). Presumably that means it would have to be\npretty brief.\n\nThanks,\nJonathan\n"}]}