[ClusterLabs] Pacemaker documentation license clarification

[Ken Gaillot]

On 12/13/2015 06:56 PM, Ferenc Wagner wrote:
> Ken Gaillot <kgaillot at redhat.com> writes:
> 
>> On 12/11/2015 10:07 AM, Ferenc Wagner wrote:
>>
>>> [...] the "Legal Notice"
>>> section of the generated Publican documentation (for example
>>> Pacemaker_Explained/desktop/en-US/index.html) says that the material may
>>> only be distributed under GFDL-1.2+.
>>
>> This is an artifact of how you're building the documentation. Easy to
>> miss given the makefile complexity :)
> 
> Especially that I did not study the doc makefiles at all, just issued
> make.
> 
>> If you look at the generated versions on clusterlabs.org, they have the
>> correct license (CC-BY-SA)
> 
> That's great.
> 
>> However if you do not "make brand" before building the documentation,
>> you will get the publican defaults.
> 
> Wouldn't --with-brand=clusterlabs also be needed?  Anyway, I can't
> really do this because of the sudo step.  But specifying --brand_dir
> helps indeed.  Is there any reason not to use the clusterlabs brand
> automatically all the time, without installation?  It goes like this:

Currently, the brand is specified in each book's publican.cfg (which is
generated by configure, and can be edited by "make www-cli"). It works,
so realistically it's a low priority to improve it, given everything
else on the plate.

You're welcome to submit a pull request to change it to use the local
brand directory. Be sure to consider that each book comes in multiple
formats (and potentially translations, though they're out of date at
this point, which is a whole separate discussion worth raising at some
point), and add anything generated to .gitignore.

> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -73,16 +73,20 @@ EXTRA_DIST	= $(docbook:%=%.xml)
>  %.html: %.txt
>  	$(AM_V_ASCII)$(ASCIIDOC) --unsafe --backend=xhtml11 $<
>  
> +# publican-clusterlabs/xsl/html-single.xsl imports that of Publican
> +# through this link during the build
> +../xsl:
> +	ln -s /usr/share/publican/xsl "$@"
>  
>  CFS_TXT=$(wildcard Clusters_from_Scratch/en-US/*.txt)
>  CFS_XML=$(CFS_TXT:%.txt=%.xml)
>  
>  # We have to hardcode the book name
>  # With '%' the test for 'newness' fails
> -Clusters_from_Scratch.build: $(PNGS) $(wildcard Clusters_from_Scratch/en-US/*.xml) $(CFS_XML)
> +Clusters_from_Scratch.build: $(PNGS) $(wildcard Clusters_from_Scratch/en-US/*.xml) $(CFS_XML) ../xsl
>  	$(PCMK_V) @echo Building $(@:%.build=%) because of $?
>  	rm -rf $(@:%.build=%)/publish/*
> -	$(AM_V_PUB)cd $(@:%.build=%) && RPM_BUILD_DIR="" $(PUBLICAN) build --publish --langs=$(DOCBOOK_LANGS) --formats=$(DOCBOOK_FORMATS) $(PCMK_quiet)
> +	$(AM_V_PUB)cd $(@:%.build=%) && RPM_BUILD_DIR="" $(PUBLICAN) build --publish --langs=$(DOCBOOK_LANGS) --formats=$(DOCBOOK_FORMATS) $(PCMK_quiet) --brand_dir=../publican-clusterlabs
>  	rm -rf $(@:%.build=%)/tmp
>  	touch $@
> 
> [...]
>