In our osmo-gsm-manuals, there are various code listings that one would like to copy-paste from the PDF. That would theoretically work, but practically, the 'DRAFT' watermark in the backdrop confuses the text marking, hence making copy-pasting some text from the manuals very very cumbersome. Though I'm not that sure why we need a 'DRAFT' watermark in an open source manual (it's implicitly a draft), I am fine with having such a marking.
But I would like the marking to be less obtrusive. We could experiment with putting a bitmap image in the backdrop instead of text, or even better IMHO would be to put it in the page header next to the version.
We could also add a generic "DRAFT" disclaimer near the beginning of each document.
(Same goes for the sysmocom internal manuals, for which it isn't so easy to get the asciidoc source to paste from.)
Any opinions on this?
~N
Hi Neels,
I do like the "DRAFT" marking as it is not a set of released manuals for a given version of the software.
Having said that, if there's a real benefit from disabling draft marking, please simply go for it.
If we ever have a set of "stable" documentation for a given version of the software, we can think on how to properly mark that version on the title pages of the manuals at that time.
I don't think it's useful use of our time trying to find other methods that enable DRAFT watermarking.
On Sun, May 14, 2017 at 03:53:02PM +0200, Harald Welte wrote:
I do like the "DRAFT" marking as it is not a set of released manuals for a given version of the software.
Having said that, if there's a real benefit from disabling draft marking, please simply go for it.
Playing around for some minutes, I found these snippets: (I did this of course before reading that I shouldn't bother with it)
Show "DRAFT" in the document header and drop the watermark:
------------------------- diff --git a/build/Makefile.asciidoc.inc b/build/Makefile.asciidoc.inc index fad91fa..82721ff 100644 --- a/build/Makefile.asciidoc.inc +++ b/build/Makefile.asciidoc.inc @@ -16,15 +16,15 @@ ASCIIDOCSTYLE ?= $(BUILDDIR)/custom-dblatex.sty cleanfiles += $(ASCIIDOCPDFS)
ASCIIDOC_OPTS := -f $(BUILDDIR)/mscgen-filter.conf -f $(BUILDDIR)/diag-filter.conf -f $(BUILDDIR)/docinfo-releaseinfo.conf -DBLATEX_OPTS := -s $(ASCIIDOCSTYLE) -P draft.mode=yes +DBLATEX_OPTS := -s $(ASCIIDOCSTYLE) -P draft.mode=yes -P draft.watermark=0
ifeq (,$(BUILD_RELEASE)) - DBLATEX_OPTS += -P draft.watermark=1 + REVNUMBER := DRAFT $(GIT_VERSION) else - DBLATEX_OPTS += -P draft.watermark=0 + REVNUMBER := $(GIT_VERSION) endif
-A2X_OPTS := -L --asciidoc-opts="$(ASCIIDOC_OPTS)" --dblatex-opts="$(DBLATEX_OPTS)" -a docinfo -a revnumber="$(GIT_VERSION)" -a revdate="$(GIT_DATE)" +A2X_OPTS := -L --asciidoc-opts="$(ASCIIDOC_OPTS)" --dblatex-opts="$(DBLATEX_OPTS)" -a docinfo -a revnumber="$(REVNUMBER)" -a revdate="$(GIT_DATE)"
all: $(ASCIIDOCPDFS) -------------------------
I also found a bit of code to put a "DRAFT" on only the first page, but I find it impossibly hard to figure out how to switch this snippet on and off depending on the 'make BUILD_RELEASE=?' option. So if we don't need it to be toggle-able, we can use it as-is. Otherwise, if someone has some dblatex magic or a nifty trick to make these two lines conditional, that would give us the conditional 'DRAFT' watermark on only the first page:
------------------------- diff --git a/build/custom-dblatex.sty b/build/custom-dblatex.sty index 66cf9a1..6d1b49d 100644 --- a/build/custom-dblatex.sty +++ b/build/custom-dblatex.sty @@ -19,6 +19,10 @@ \usepackage{alltt} \usepackage{upquote}
+% "DRAFT" on first page +\definecolor{LtGrey}{rgb}{0.8,0.8,0.8} +\AddToShipoutPicture*{ \AtTextCenter{ \makebox(0,0)[c]{\resizebox{\textwidth}{!}{ \rotatebox{45}{\textsf{\textbf{\color{LtGrey}DRAFT}}}}} } } + \def\Company{sysmocom - s.f.m.c. GmbH}
\def\DBKcover{ -------------------------
That's enough dblatex for me now, asciidoc is so much easier to understand.
~N
I was recently annoyed by the DRAFT watermark again when re-configuring a sysmoBTS for the osmo-gsm-tester and trying to paste from the manual.
On Sun, May 14, 2017 at 08:05:11PM +0200, Neels Hofmeyr wrote:
Playing around for some minutes, I found these snippets:
Show "DRAFT" in the document header and drop the watermark:
[...]
I also found a bit of code to put a "DRAFT" on only the first page, but I find it impossibly hard to figure out how to switch this snippet on and off
[...]
No ideas anyone to switch on/off a bit of dblatex.sty?
We can show "DRAFT" on the first page always, needing manual .sty editing to disable the DRAFT. No-one ever seems to render without the DRAFT watermark anyway.
I submitted both as separate patches, https://gerrit.osmocom.org/2838 https://gerrit.osmocom.org/2839
~N
-
Harald Welte -
Neels Hofmeyr