Patchwork [2/5] manual: add a make target 'manual-update-lists'

login
register
mail settings
Submitter Samuel Martin
Date March 12, 2013, 4:47 a.m.
Message ID <da0b536e458646ecade2fd7d2a8cee2e04148e66.1363063387.git.s.martin49@gmail.com>
Download mbox | patch
Permalink /patch/226767/
State Superseded
Headers show

Comments

Samuel Martin - March 12, 2013, 4:47 a.m.
Signed-off-by: Samuel Martin <s.martin49@gmail.com>

---
Changes since v2:
* remove PYTHONPATH stuff since the kconfiglib module is next to
  gen-manual-lists.py (Arnout)

Changes since v1:
* add manual-update-lists target to the .PHONY one (Arnout)
* misc. fixes/updates
---
 docs/manual/manual.mk | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)
Thomas Petazzoni - March 12, 2013, 7:59 a.m.
Dear Samuel Martin,

On Tue, 12 Mar 2013 05:47:15 +0100, Samuel Martin wrote:

> +manual-update-lists:
> +	@$(call MESSAGE,"Updating the manual lists...")
> +	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) \
> +		$(TOPDIR)/support/scripts/gen-manual-lists.py

Sorry if this has been discussed before. Why don't we make this part of
the normal manual build process (make manual-pdf, make manual-html,
etc.), so that we don't have to version control the generated lists of
packages, and this updating of the lists is done automatically whenever
we generate the manual?

Best regards,

Thomas
Samuel Martin - March 12, 2013, 8:41 a.m.
Hi Thomas,

2013/3/12 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> Dear Samuel Martin,
>
> On Tue, 12 Mar 2013 05:47:15 +0100, Samuel Martin wrote:
>
>> +manual-update-lists:
>> +     @$(call MESSAGE,"Updating the manual lists...")
>> +     $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) \
>> +             $(TOPDIR)/support/scripts/gen-manual-lists.py
>
> Sorry if this has been discussed before. Why don't we make this part of
> the normal manual build process (make manual-pdf, make manual-html,
> etc.), so that we don't have to version control the generated lists of
> packages, and this updating of the lists is done automatically whenever
> we generate the manual?
I don't remember we discussed a lot this point.

I don't have a strong opinion about this, but since there is some
date/version in
the generated files (see patch 5/5), I don't want to bother people
with this insignificant
change just because they (re)build the manual...

Regards,
Arnout Vandecappelle - March 12, 2013, 10:04 p.m.
On 03/12/13 08:59, Thomas Petazzoni wrote:
> Dear Samuel Martin,
>
> On Tue, 12 Mar 2013 05:47:15 +0100, Samuel Martin wrote:
>
>> +manual-update-lists:
>> +	@$(call MESSAGE,"Updating the manual lists...")
>> +	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) \
>> +		$(TOPDIR)/support/scripts/gen-manual-lists.py
>
> Sorry if this has been discussed before. Why don't we make this part of
> the normal manual build process (make manual-pdf, make manual-html,
> etc.), so that we don't have to version control the generated lists of
> packages, and this updating of the lists is done automatically whenever
> we generate the manual?

  Originally, the generated list was still modified manually. But I don't 
think that is needed anymore, so indeed I would do it automatically as 
part of the 'make manual' step.


  Regards,
  Arnout
Thomas Petazzoni - March 13, 2013, 7:39 a.m.
Dear Samuel Martin,

On Tue, 12 Mar 2013 09:41:27 +0100, Samuel Martin wrote:

> I don't have a strong opinion about this, but since there is some
> date/version in
> the generated files (see patch 5/5), I don't want to bother people
> with this insignificant
> change just because they (re)build the manual...

I'm not sure to understand the problem with the dates. I'd say you
shouldn't put the date specifically in the list of packages. I would
expect "make manual-pdf" to generate the list of packages with your
script, get it included into the manual sources, and get the manual
built.

Separately, we may want to introduce something at the beginning of the
manual that says at which date the manual was built, and on which Git
version of the Buildroot sources. But I don't see a reason to make this
related to the list of packages specifically.

Best regards,

Thomas
Samuel Martin - March 19, 2013, 9:52 p.m.
Hi Thomas,

2013/3/13 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> Dear Samuel Martin,
>
> On Tue, 12 Mar 2013 09:41:27 +0100, Samuel Martin wrote:
>
>> I don't have a strong opinion about this, but since there is some
>> date/version in
>> the generated files (see patch 5/5), I don't want to bother people
>> with this insignificant
>> change just because they (re)build the manual...
>
> I'm not sure to understand the problem with the dates. I'd say you
> shouldn't put the date specifically in the list of packages. I would
> expect "make manual-pdf" to generate the list of packages with your
> script, get it included into the manual sources, and get the manual
> built.
>
> Separately, we may want to introduce something at the beginning of the
> manual that says at which date the manual was built, and on which Git
> version of the Buildroot sources. But I don't see a reason to make this
> related to the list of packages specifically.
Just to be sure, here, you mean something like a non-versioned version.txt file,
which would be automatically generated and included in manual.txt?


Regards,
Thomas Petazzoni - March 20, 2013, 8:25 a.m.
Dear Samuel Martin,

On Tue, 19 Mar 2013 22:52:11 +0100, Samuel Martin wrote:

> > I'm not sure to understand the problem with the dates. I'd say you
> > shouldn't put the date specifically in the list of packages. I would
> > expect "make manual-pdf" to generate the list of packages with your
> > script, get it included into the manual sources, and get the manual
> > built.
> >
> > Separately, we may want to introduce something at the beginning of the
> > manual that says at which date the manual was built, and on which Git
> > version of the Buildroot sources. But I don't see a reason to make this
> > related to the list of packages specifically.
> Just to be sure, here, you mean something like a non-versioned version.txt file,
> which would be automatically generated and included in manual.txt?

Yes, something like that.

Best regards,

Thomas
Lionel Orry - March 20, 2013, 12:58 p.m.
Hi all,

On Wed, Mar 20, 2013 at 9:25 AM, Thomas Petazzoni
<thomas.petazzoni@free-electrons.com> wrote:
> Dear Samuel Martin,
>
> On Tue, 19 Mar 2013 22:52:11 +0100, Samuel Martin wrote:
>
>> > I'm not sure to understand the problem with the dates. I'd say you
>> > shouldn't put the date specifically in the list of packages. I would
>> > expect "make manual-pdf" to generate the list of packages with your
>> > script, get it included into the manual sources, and get the manual
>> > built.
>> >
>> > Separately, we may want to introduce something at the beginning of the
>> > manual that says at which date the manual was built, and on which Git
>> > version of the Buildroot sources. But I don't see a reason to make this
>> > related to the list of packages specifically.
>> Just to be sure, here, you mean something like a non-versioned version.txt file,
>> which would be automatically generated and included in manual.txt?
>
> Yes, something like that.

Can I suggest something like adding this line at the beginning of the manual:

Manual generated from git revision {sys:git rev-parse HEAD} on
{docdate} {doctime}.

This avoids an extra file generation, asciidoc can do it by itself.

Lionel

>
> Best regards,
>
> Thomas
> --
> Thomas Petazzoni, Free Electrons
> Kernel, drivers, real-time and embedded Linux
> development, consulting, training and support.
> http://free-electrons.com
> _______________________________________________
> buildroot mailing list
> buildroot@busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
Thomas Petazzoni - March 20, 2013, 1:49 p.m.
Dear Lionel Orry,

On Wed, 20 Mar 2013 13:58:26 +0100, Lionel Orry wrote:

> Can I suggest something like adding this line at the beginning of the manual:
> 
> Manual generated from git revision {sys:git rev-parse HEAD} on
> {docdate} {doctime}.
> 
> This avoids an extra file generation, asciidoc can do it by itself.

Sounds even better! Thanks for the suggestion.

Thomas

Patch

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index aa20534..012d0e7 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -24,6 +24,11 @@  $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt $$($(call UPPERCASE,$(1))_SOURCES)
 	  -D $$(@D) $$<
 endef
 
+manual-update-lists:
+	@$(call MESSAGE,"Updating the manual lists...")
+	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) \
+		$(TOPDIR)/support/scripts/gen-manual-lists.py
+
 ################################################################################
 # GENDOC -- generates the make targets needed to build asciidoc documentation.
 #
@@ -41,8 +46,9 @@  $(call GENDOC_INNER,$(1),epub,epub,epub,EPUB)
 clean: $(1)-clean
 $(1)-clean:
 	$(Q)$(RM) -rf $(O)/docs/$(1)
-.PHONY: $(1) $(1)-clean
+.PHONY: $(1) $(1)-clean manual-update-lists
 endef
 
 MANUAL_SOURCES = $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)
 $(eval $(call GENDOC,manual))
+