From: Jakub Narebski <jnareb@gmail.com>
Date: Mon, 10 Oct 2011 22:02:24 GMT
Subject: Re: [PATCHv5/RFC 3/6] gitweb: Add manpage for gitweb
Message-ID: <201110110002.24665.jnareb@gmail.com>
In-Reply-To: <7vr52kk1jj.fsf@alter.siamese.dyndns.org>

On Mon, 10 Oct 2011, Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
> > diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt
> > new file mode 100644
> > index 0000000..2acdb3b
> > --- /dev/null
> > +++ b/Documentation/gitweb.txt
> > @@ -0,0 +1,703 @@
> > +gitweb(1)
> > +=========
> > +
> > +NAME
> > +----
> > +gitweb - Git web interface (web frontend to Git repositories)
> > +
> > +SYNOPSIS
> > +--------
> > +To get started with gitweb, run linkgit:git-instaweb[1] from a git repository.
> > +This would configure and start your web server, and run web browser pointing to
> > +gitweb page.
> > +
> > +See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb[] or
> > +http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code,
> > +browsed using gitweb itself.
> 
> This doesn't quite look like a "SYNOPSIS" section. Shouldn't everything
> after the first line be at the beginning of "DESCRIPTION"?

Did you mean something like (it would have to be slightly adjusted,
of course):
 
    +SYNOPSIS
    +--------
    +To get started with gitweb, run linkgit:git-instaweb[1] from a git repository.
    +
    +DESCRIPTION
    +-----------
    +This would configure and start your web server, and run web browser pointing to
    +gitweb page.

The problem is that catering to old AsciiDoc (but still used by some of
long-term-support Linux distributions) requires to have "SYNOPSIS"
section... but there is no natural synopsis for non self-hostable web
application, is there?

-- 
Jakub Narebski
Poland