[PATCH] Documentation: add a README file

[PATCH] Documentation: add a README file

[Yann Droneaud]

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

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

Re: [PATCH] Documentation: add a README file

[Junio C Hamano]

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?

Re: [PATCH] Documentation: add a README file

[Yann Droneaud]

Le 21.03.2013 16:31, Junio C Hamano a écrit :
> 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

Re: [PATCH] Documentation: add a README file

[Junio C Hamano]

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.

Re: [PATCH] Documentation: add a README file

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> 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(+)

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

Re: [PATCH] Documentation: add a README file

[Yann Droneaud]

Le jeudi 21 mars 2013 à 10:39 -0700, Junio C Hamano a écrit :
> 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

Re: [PATCH] Documentation: add a README file

[Yann Droneaud]

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

Re: [PATCH] Documentation: add a README file

[Jonathan Nieder]

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