Hello, On Sat 20 Jul 2019 at 07:27PM +01, Ian Jackson wrote:
> 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.
My problem with the end-of-line shell comments is not the runes leading
the prose, so I'd be happy to switch them over. My problem is how much
harder it is to visually distinguish the commands from their labels.
An alternative which would satisfy these concerns and hopefully yours
too would be this:
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 (e.g.) Debian's salsa
git debrebase conclude && dgit push-source
# do a source-only upload
git debrebase [-i] new-upstream 1.2.3
# import upstream tag (e.g.) '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".
git-debrebase has a special branch format, so see "CONVERTING AN
EXISTING PACKAGE" in L<dgit-maint-debrebase(7)>.
I've tried both removing the indent before the comments, and moving the
comments to the end of the lines with runes, and in both cases I find it
very hard to visually distinguish runes from labels, such that I find it
hard to extract information from the quick reference.
> - You interrupt the vertically aligned structure of the runes,
> making the thing seem messier.
Hopefully what I suggest just above avoids this.
> - 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
Okay.
> - 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.
I have the opposite intuition about clumsiness, and I think both are
grammatical, but I certainly don't mind switching it back!
> - 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).
Yes.
--
Sean Whitton
From 7c472f10607de388380a22a4d77c6fb90c77c055 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhit...@spwhitton.name>
Date: Sat, 20 Jul 2019 13:00:34 +0100
Subject: [PATCH] git-debrebase(1): Make this manpage a less intimidating entry
point
- Nicer short description right in the first section.
- Don't use the term 'delta queue' until it's needed.
- Don't talk about other manpages so early.
- Cater for people who type `man git-debrebase` looking for a
barebones tutorial, not (just) a command line reference.
- That tutorial should minimise references to dgit, especially since
users might want to use git-debpush to upload.
Thanks to Sam Hartman for the user feedback which prompted this and
Ian Jackson for feedback on the content of "QUICK REFERENCE".
Closes: #926656
Signed-off-by: Sean Whitton <spwhit...@spwhitton.name>
---
git-debrebase.1.pod | 33 ++++++++++++++++++++++++++-------
1 file changed, 26 insertions(+), 7 deletions(-)
diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index af6e3646..90fe1aac 100644
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -1,21 +1,40 @@
=head1 NAME
-git-debrebase - delta queue rebase tool for Debian packaging
+git-debrebase - tool to maintain series of Debian changes to upstream source
=head1 SYNOPSYS
git-debrebase [<options...>] [-- <git-rebase options...>]
git-debrebase [<options...>] <operation> [<operation options...>
-=head1 INTRODUCTION
+=head1 QUICK REFERENCE
-git-debrebase is a tool for representing in git,
-and manpulating,
-Debian packages based on upstream source code.
+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 (e.g.) Debian's salsa
+ git debrebase conclude && dgit push-source
+ # do a source-only upload
+ git debrebase [-i] new-upstream 1.2.3
+ # import upstream tag (e.g.) '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".
+
+git-debrebase has a special branch format, so see "CONVERTING AN
+EXISTING PACKAGE" in L<dgit-maint-debrebase(7)>.
+
+=head1 GUIDE TO DOCUMENTATION
This is the command line reference.
-Please read the tutorial
-L<dgit-maint-debrebase(7)>.
+There is also a detailed workflow tutorial at
+L<dgit-maint-debrebase(7)>
+(on which the above "QUICK REFERENCE" is based).
For background, theory of operation,
and definitions see L<git-debrebase(5)>.
--
2.20.1
signature.asc
Description: PGP signature
