Feature #159
openREADME.doc not part of skeleton...
Added by François Félix Ingrand over 6 years ago. Updated over 6 years ago.
Description
Currently README.doc (asciidoc) is produced by skeleton.
Could it be produced by is own template (e.g. doc) or can you add an option to skeleton (e.g. -d) to only produce the doc (so we could update README.doc without having to invoke skeleton -i and making sure the codels are not modified.)
My feeling is that it should be in its own template.
My 2 cents.
Files
| signature.asc (833 Bytes) signature.asc | François Félix Ingrand, 2018-05-08 10:21 | ||
| signature.asc (833 Bytes) signature.asc | François Félix Ingrand, 2018-05-09 08:57 |
Updated by Anthony Mallet over 6 years ago
Since the README.adoc is part of the source of the component, and not
standalone generated code, it makes sense that it is generated by
skeleton - whose purpose is to bootstrap a component.
Also, doc generation can be disabled with the -t option.
I don't like so much the idea of having an extra template for the doc:
- it would complexify the bootstrap when starting a component from
scratch: two steps instead of one.
- it would complexify the sample Makefile.am, and would require magic
so that both skeleton and doc templates can add their rules,
probably via 'include' or something. Since most users are already
lost with autoconf, I don't this this would help.
- it would probably make all components being published without doc,
since we know that asking users to do something more that the bare
required minimum is bound to fail.
skeleton -i will never change codels unless to explicitly accept the
changes it suggests; and it will normally not suggest anything if
everything is up-to-date.
What is your real issue? I feel that this is what should be fixed instead.
Updated by François Félix Ingrand over 6 years ago
- File signature.asc signature.asc added
On 07 May 2018, at 21:59, Anthony Mallet <anthony.mallet@laas.fr> wrote:
Issue #159 has been updated by Anthony Mallet.
Since the README.adoc is part of the source of the component, and not
standalone generated code, it makes sense that it is generated by
skeleton - whose purpose is to bootstrap a component.
Also, doc generation can be disabled with the -t option.
So the way you see it, people just put some doc fields in the .gen to get started, bootstrap the README.doc and then modify the later only? This is cumbersome.
Why not consider that README.doc is not part of the source of the component (as its content is completely generated from .gen).
I think code/doc should be modified in one place only… and keeping the doc in the .gen only is probably a good idea. So the README.doc should be updated as the .gen is updated. Calling skeleton to do this is fine, but it keeps proposing me to revert changes in my codels/Makefile.am where I have added files and compile FLAGS, etc.
Updated by Anthony Mallet over 6 years ago
On Tuesday 8 May 2018, at 10:21, François Ingrand wrote:
So the way you see it, people just put some doc fields in the .gen to
get started, bootstrap the README.doc and then modify the later only?
This is cumbersome.
No, I don't see it like this :)
skeleton -i is (most of the time) able to merge changes from the .gen
to the .adoc file and preserve user modifications.
Why not consider that README.doc is not part of the source of the
component (as its content is completely generated from .gen).
Because if feel is important to have the doc in the source. Especially
if there are user additions. (and by the way having the .adoc file in
the source tree is needed to get the "gollum" functionality).
I think code/doc should be modified in one place only… and keeping the
doc in the .gen only is probably a good idea. So the README.doc should
be updated as the .gen is updated.
Yes, I agree and this is how it works :)
Calling skeleton to do this is
fine, but it keeps proposing me to revert changes in my
codels/Makefile.am where I have added files and compile FLAGS, etc.
Probably because you have written your Makefile.am in a way that makes
skeleton lost when it tries to figure out the changes you made.
When this happen to me I try to fix the merge algorithm, but it's been
a long time that I haven't been hit by such a mistake from skeleton.
Without a concrete example of skeleton failing to merge user changes
with it's own updates, I can't look at it, though.
Updated by François Félix Ingrand over 6 years ago
- File signature.asc signature.asc added
I think code/doc should be modified in one place only… and keeping the
doc in the .gen only is probably a good idea. So the README.doc should
be updated as the .gen is updated.Yes, I agree and this is how it works :)
Not quite, unless I missed something, README.doc is only updated when you call the skeleton template explicitly, while there are templates (e.g. mappings) which get called automatically when you touch the .gen . I think that the README.doc should be produced the same way.
Calling skeleton to do this is
fine, but it keeps proposing me to revert changes in my
codels/Makefile.am where I have added files and compile FLAGS, etc.Probably because you have written your Makefile.am in a way that makes
skeleton lost when it tries to figure out the changes you made.
Here is an example:
merging ./codels/Makefile.am
--- ./codels/Makefile.am Tue Feb 20 09:30:20 CET 2018
+++ ./codels/Makefile.am Wed May 09 08:53:27 CEST 2018
@@ -5,13 +5,8 @@
libNavigation_codels_la_SOURCES= Navigation_c_types.h
libNavigation_codels_la_SOURCES+= Navigation_codels.cc
libNavigation_codels_la_SOURCES+= Navigation_navigate_codels.cc
-
-
-libNavigation_codels_la_SOURCES+= Graph.hpp codels.h
-libNavigation_codels_la_SOURCES+= Graph.cpp GraphIO.cpp
-
-
-libNavigation_codels_la_CPPFLAGS= $(requires_CFLAGS) -Wall -Wextra -I${HOME}/work/Mauve/mauve_types/include -std=gnu++11
+
+libNavigation_codels_la_CPPFLAGS= $(requires_CFLAGS)
libNavigation_codels_la_LDFLAGS= $(requires_LIBS)
libNavigation_codels_la_LDFLAGS+= -release $(PACKAGE_VERSION)
Apply this patch [y,n,c,a,q,?]?
it wants to “remove” the sources file I added. :-(
When this happen to me I try to fix the merge algorithm, but it's been
a long time that I haven't been hit by such a mistake from skeleton.
Without a concrete example of skeleton failing to merge user changes
with it's own updates, I can't look at it, though.
—
Felix