Hi, Colin. Sorry to bring you into this unexpectedly. I'm hoping you
might have time to have an opinion on the git-debrebase manpage.
We're proposing to add a QUICK REFERENCE section very near the top,
and are debating what it should be like.
Sean Whitton writes ("Re: Bug#926656: git-debrebase docs are intimidating"):
> I'm inclined to agree with this assessment, but it would be useful to
> hear from Sam's imaginary new user perspective.
Yes.
> On Sat 20 Jul 2019 at 05:34PM +01, Ian Jackson wrote:
> > How about:
> >
> > QUICK REFERENCE
> >
> > These are most of the commands you will regularly need:
> >
> > % git debrebase -i # edit the queue of patches
> > % dpkg-buildpackage -uc -b # build test binaries, at any time
> > % git debrebase conclude && git push # push to eg salsa
> > % git debrebase conclude && dgit push-source # source-only upload
> > % git debrebase [-i] new-upstream 1.2.3-1 # uses tag, eg "v1.2.3"
> >
> > To add patches, or edit the packaging, just make git commits.
> > Ignore anything that may appear in debian/patches.
> > Avoid using "git pull" and "git merge" without "--ff-only".
> >
> > See the tutorial manpage dgit-maint-debrebase for how to
> > convert your branch into the git-debrebase format.
>
> Assuming what you're proposing is substituting this for QUICK REFERENCE
> in my patch, and keeping my other changes, I think this is really good.
Err, I didn't read much of the rest of the patch....
.... oh you mean the NAME change and the thing at the end. Fine by
me.
> Just one thing: I find the use of shell comments at the end of lines
> makes the block of runes difficult to read. I agree that there is the
> potential for intimidation if they are as spread out as they are in my
> first patch, though. I've done something in between in the attached.
Hmm. IMO:
- Your approach uses 3 times as much vertical space. The whole QR
runeset doesn't now appear in the first page in a 25 line terminal.
- It leads with prose, not the runes. But the runes are supposed
to be mostly self-explanatory. I think they are the primary
content. The comments are footnotes. I'm hoping the user can
navigate the list of runes by simply intuiting what they are likely
to do. Presenting them this way is also an implicit promise that
they do what the reader will expect.
- You interrupt the vertically aligned structure of the runes,
making the thing seem messier.
- Overall it feels bigger. We want it to feel small. So it should be
as brief as we can possibly make it.
Generally, I think quick references are normally dense and where the
effect of a command or facility is obvious often do not contain any
prose at all. Here is a nice one for PostScript (although more
useful to the working PostScript programmer than the newcomer).
http://pstricks.tug.org/PS/quick-ref.PS.pdf
- Not sure why you swapped "need" and "regularly". Ends of things
just before : are more prominent and I think "need" deserves that
spot. Also I find this word order clumsy - maybe even not proper
grammar.
- Maybe we can delete some unnecessary words from the cross reference
to keep it really short (from my version too). Eg
"{-the tutorial manpage-}". If you mention the section name maybe
the explanation is not needed to, so maybe simply
git-debrebase has a special branch format, so see "CONVERTING AN
EXISTING PACKAGE" in dgit-maint-debrebase(7).
I would like to hear from Sam, and maybe someone else (Colin maybe,
since he made a comment about the dgit manpage which might be resolved
i a similar way). In the interests of making that review easy, here
is a formatted version of Sean's version:
> QUICK REFERENCE
>
> These are most of the commands you will need regularly:
>
> Edit the queue of patches
> % git debrebase -i
>
> Build test binaries, at any time
> % dpkg-buildpackage -uc -b
>
> Push to an ordinary git remote (e.g. Debian's salsa)
> % git debrebase conclude && git push
>
> Do a source-only upload
> % git debrebase conclude && dgit push-source
>
> New upstream release (using an upstream tag like 'v1.2.3')
> git debrebase [-i] new-upstream 1.2.3
>
> To add patches, or edit the packaging, just make git commits. Ignore
> anything that may appear in debian/patches. Avoid using "git pull" and
> "git merge" without "--ff-only".
>
> See the tutorial manpage dgit-maint-debrebase(7), section "CONVERTING
> AN EXISTING PACKAGE", for how to convert your branch into the git-
> debrebase format.
--
Ian Jackson <ijack...@chiark.greenend.org.uk> These opinions are my own.
If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.
