threads / patch / 33248

patchDocumentation: add a README file

Subject: [PATCH] Documentation: add a README file

## tl;dr

8 messages between Mar 21, 2013 and Mar 21, 2013. Diffs are folded; open one to read it.

replies: 7people: 3as markdown or json

Yann Droneaud· Mar 21, 2013, 13:45 UTC · lore

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 <ydroneaud@opteya.com>
---
 Documentation/README | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 Documentation/README
Show changes to Documentation/README +13 −0
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· Mar 21, 2013, 15:31 UTC · re: Yann Droneaud · lore

Re: [PATCH] Documentation: add a README file

Yann Droneaud <ydroneaud@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?

Yann Droneaud· Mar 21, 2013, 15:49 UTC · re: Junio C Hamano · lore

Re: [PATCH] Documentation: add a README file

Le 21.03.2013 16:31, Junio C Hamano a écrit :
Show 8 quoted lines
> Yann Droneaud <ydroneaud@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
Junio C Hamano· Mar 21, 2013, 17:39 UTC · re: Yann Droneaud · lore

Re: [PATCH] Documentation: add a README file

Yann Droneaud <ydroneaud@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.

Junio C Hamano· Mar 21, 2013, 21:16 UTC · re: Junio C Hamano · lore

Re: [PATCH] Documentation: add a README file

Junio C Hamano <gitster@pobox.com> writes:
Show 7 quoted lines
> Yann Droneaud <ydroneaud@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(+)
Show changes to Documentation/CodingGuidelines +3 −0
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· Mar 21, 2013, 22:02 UTC · re: Junio C Hamano · lore

Re: [PATCH] Documentation: add a README file

Hi,
Le jeudi 21 mars 2013 à 14:16 -0700, Junio C Hamano a écrit :
Show 16 quoted lines
> 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
Yann Droneaud· Mar 21, 2013, 21:59 UTC · re: Junio C Hamano · lore

Re: [PATCH] Documentation: add a README file

Le jeudi 21 mars 2013 à 10:39 -0700, Junio C Hamano a écrit :
Show 8 quoted lines
> Yann Droneaud <ydroneaud@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
Jonathan Nieder· Mar 21, 2013, 22:09 UTC · re: Yann Droneaud · lore

Re: [PATCH] Documentation: add a README file

Yann Droneaud wrote:
Show 9 quoted lines
> 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

← back to recent threads