| Message ID | 20201016205232.2546562-2-emilyshaffer@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | some small clarifying docfixes | expand |
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
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
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.
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 --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.
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(-)