Sean Whitton writes ("Bug#926656: git-debrebase docs are intimidating"):
> An alternative which would satisfy these concerns and hopefully yours
> too would be this:

In your version I find it difficult to separate commands out from the
labels.  Which is precisely your problem with my version.

How about this ?

>From f8bd77368107246e3652b4e8074c7c09f4ebde18 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>
Signed-off-by: Ian Jackson <ijack...@chiark.greenend.org.uk>
---
 git-debrebase.1.pod | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 6f328dd9..d1b4507f 100644
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -1,21 +1,35 @@
 =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 patch queue
+ 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"
+ dpkg-buildpackage -uc -b                   # get test debs, at any time
+
+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.11.0

Reply via email to