From: Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com>
Date: Mon, 12 Jan 2026 16:11:09 GMT
Subject: Re: [PATCH] doc: MyFirstContribution: fix missing dependencies and clarify build steps
Message-ID: <20260112161538.351527-1-shreyanshpaliwalcmsmn@gmail.com>
In-Reply-To: <xmqqcy3eoq6e.fsf@gitster.g>

> > Fix several issues in the MyFirstContribution guide that can lead to
> > confusion or test failures when following the documented steps.
> >
> > * Add missing header includes in code examples (environment.h and
> > strbuf.h).
> >
> > *  correct manpage synopsis formatting to prevent failing documentation tests.
> 
> Two spaces???

Sorry, my bad. Will fix it in v2.

> >  Then, add the following bits to the function body:
> >  function body:
> >  
> > @@ -429,6 +430,7 @@ Add the following includes:
> >  ----
> >  #include "commit.h"
> >  #include "pretty.h"
> > +#include "strbuf.h"
> >  ----
> >  
> >  Then, add the following lines within your implementation of `cmd_psuh()` near
> > @@ -504,7 +506,7 @@ git-psuh - Delight users' typo with a shy horse
> >  SYNOPSIS
> >  --------
> >  [verse]
> > -'git-psuh [<arg>...]'
> > +git psuh [<arg>...]
> 
> Removing "-" does make sense but did you really want to remove the
> quotes around the command?  If you are moving to the [synopsis]
> style from [verse] (*), it may make sense, but otherwise...?
> 
>     Side note: see de56e1d7 (Merge branch
>     'ja/doc-commit-markup-updates', 2025-01-29) for example.

Actually, I initially kept the quotes, but the test that checks consistency between
the manpage synopsis and the -h output was still failing. At that point, my intention
was to switch to the [synopsis] style, so I removed the quotes, but I missed updating
the markup from [verse] to [synopsis].
Will fix this as well in v2.

> >  NOTE: Before trying to build the docs, make sure you have the package `asciidoc`
> > -installed.
> > +and `docbook-xsl` installed. See `INSTALL` for details.
> 
> I suspect this is highly distribution specific.  The asciidoc
> package is typically packaged to depend on or suggest the docbook
> toolchain including docbook-xsl, and if we start adding more "to
> help newbies", we'd face the problem of "where would we stop?".  For
> example, on Debian derived systems, the docbook-xsl package
> typicallly depends on the xml-core package---should we also list it?
> 
> I personally find that stopping at asciidoc and let the user deal
> with their platform convention to get asciidoc working, like the
> current documentation does, draws the line better than the above
> updated text.

I totally agree with the “where would we stop?” concern, that is also
why I intentionally avoided calling out Windows or any linux-distro
specific details elsewhere in the document.

My thinking here was that docbook-xsl felt more like a peer dependency
to asciidoc rather than a deeper, transitive one (like xml-core),
especially since it is explicitly mentioned in INSTALL doc.

An alternative could be to keep it less concrete and say something like

	“make sure you have the `asciidoc` installed along with the
	 required docbook toolchain. Refer INSTALL for details”

Please let me know what would be the appropriate approach with this.

Best,
Shreyansh