diff mbox series

[1/2] MyFirstContribution: clarify asciidoc dependency

Message ID 20201016205232.2546562-2-emilyshaffer@google.com
State New
Headers show
Series some small clarifying docfixes | expand

Commit Message

Emily Shaffer Oct. 16, 2020, 8:52 p.m. UTC
Per IRC:

[19:52] <lkmandy> With respect to the MyFirstContribution tutorial, I
will like to suggest this - Under the section "Adding Documentation",
just before the "make all doc" command, it will be really helpful to
prompt a user to check if they have the asciidoc package installed, if
they don't, the command should be provided or they can just be pointed
to install it

So, let's move the note about the dependency to before the build command
blockquote.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
 Documentation/MyFirstContribution.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

Comments

Junio C Hamano Oct. 16, 2020, 9:21 p.m. UTC | #1
Emily Shaffer <emilyshaffer@google.com> writes:

> Per IRC:
>
> [19:52] <lkmandy> With respect to the MyFirstContribution tutorial, I
> will like to suggest this - Under the section "Adding Documentation",
> just before the "make all doc" command, it will be really helpful to
> prompt a user to check if they have the asciidoc package installed, if
> they don't, the command should be provided or they can just be pointed
> to install it
>
> So, let's move the note about the dependency to before the build command
> blockquote.

Suggesting asciidoc alone may not be all that helpful, or unless it
drags xmlto, docbook and friends as its dependencies, and the
details of that depends on distro packaging.

As this is only moving the existing note around in the
documentation, it is not making things any worse, so I am OK to take
the patch as-is, but if somebody (it is fine if it were done by you,
Emily) can double check "apt-get install asciidoc" on a vanilla box
does bring in what we need, that would be quite good.  FWIW, we
write in our top-level INSTALL file that we require asciidox/xmlto
toolchain (the latter is needed if you format for manpage, i.e. if
you do "git subcmd --help").

Thanks
Taylor Blau Oct. 16, 2020, 9:52 p.m. UTC | #2
On Fri, Oct 16, 2020 at 02:21:53PM -0700, Junio C Hamano wrote:
> As this is only moving the existing note around in the
> documentation, it is not making things any worse, so I am OK to take
> the patch as-is, but if somebody (it is fine if it were done by you,
> Emily) can double check "apt-get install asciidoc" on a vanilla box
> does bring in what we need, that would be quite good.  FWIW, we
> write in our top-level INSTALL file that we require asciidox/xmlto
> toolchain (the latter is needed if you format for manpage, i.e. if
> you do "git subcmd --help").

I was curious myself, and surprised to learn that 'apt-get install
asciidoc' installs more than 2GB of dependencies. Yikes. Unsurprisingly,
somewhere in those 2GB we manage to fit in everything that seems to
matter, since:

  $ cat /etc/os-release | grep PRETTY
  PRETTY_NAME="Debian GNU/Linux 9 (stretch)"
  $ apt-get update && apt-get install asciidoc
  $ cd copy-of-git
  $ make -C doc

...works just fine.

Thanks,
Taylor
Junio C Hamano Oct. 16, 2020, 10:48 p.m. UTC | #3
Taylor Blau <me@ttaylorr.com> writes:

> On Fri, Oct 16, 2020 at 02:21:53PM -0700, Junio C Hamano wrote:
>> As this is only moving the existing note around in the
>> documentation, it is not making things any worse, so I am OK to take
>> the patch as-is, but if somebody (it is fine if it were done by you,
>> Emily) can double check "apt-get install asciidoc" on a vanilla box
>> does bring in what we need, that would be quite good.  FWIW, we
>> write in our top-level INSTALL file that we require asciidox/xmlto
>> toolchain (the latter is needed if you format for manpage, i.e. if
>> you do "git subcmd --help").
>
> I was curious myself, and surprised to learn that 'apt-get install
> asciidoc' installs more than 2GB of dependencies. Yikes. Unsurprisingly,
> somewhere in those 2GB we manage to fit in everything that seems to
> matter, since:
>
>   $ cat /etc/os-release | grep PRETTY
>   PRETTY_NAME="Debian GNU/Linux 9 (stretch)"
>   $ apt-get update && apt-get install asciidoc
>   $ cd copy-of-git
>   $ make -C doc
>
> ...works just fine.

OK, that makes me feel even better.

Thanks.
Emily Shaffer Oct. 22, 2020, 11:14 p.m. UTC | #4
On Fri, Oct 16, 2020 at 03:48:39PM -0700, Junio C Hamano wrote:
> 
> Taylor Blau <me@ttaylorr.com> writes:
> 
> > On Fri, Oct 16, 2020 at 02:21:53PM -0700, Junio C Hamano wrote:
> >> As this is only moving the existing note around in the
> >> documentation, it is not making things any worse, so I am OK to take
> >> the patch as-is, but if somebody (it is fine if it were done by you,
> >> Emily) can double check "apt-get install asciidoc" on a vanilla box
> >> does bring in what we need, that would be quite good.  FWIW, we
> >> write in our top-level INSTALL file that we require asciidox/xmlto
> >> toolchain (the latter is needed if you format for manpage, i.e. if
> >> you do "git subcmd --help").
> >
> > I was curious myself, and surprised to learn that 'apt-get install
> > asciidoc' installs more than 2GB of dependencies. Yikes. Unsurprisingly,
> > somewhere in those 2GB we manage to fit in everything that seems to
> > matter, since:
> >
> >   $ cat /etc/os-release | grep PRETTY
> >   PRETTY_NAME="Debian GNU/Linux 9 (stretch)"
> >   $ apt-get update && apt-get install asciidoc
> >   $ cd copy-of-git
> >   $ make -C doc
> >
> > ...works just fine.
> 
> OK, that makes me feel even better.

Thanks for checking it, Taylor.
 - Emily
diff mbox series

Patch

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 4f85a089ef..7522387ae1 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -507,6 +507,9 @@  documentation is consistent with other Git and UNIX manpages; this makes life
 easier for your user, who can skip to the section they know contains the
 information they need.
 
+NOTE: Before trying to build the docs, make sure you have the package `asciidoc`
+installed.
+
 Now that you've written your manpage, you'll need to build it explicitly. We
 convert your AsciiDoc to troff which is man-readable like so:
 
@@ -522,8 +525,6 @@  $ make -C Documentation/ git-psuh.1
 $ man Documentation/git-psuh.1
 ----
 
-NOTE: You may need to install the package `asciidoc` to get this to work.
-
 While this isn't as satisfying as running through `git help`, you can at least
 check that your help page looks right.