Introduce makefile #54

cryptointerest · 2021-04-30T19:33:35Z

Indroduction of the makefile now with clean rebase.
I suggest postponing changing the scripts for adding the iso date formate to later until all changes have been merged.

These changes introduce the first batch of make automations for building the user guide as well as creating release tar balls.

New rules (one, don't pick up the phone, two ...):

Makefile

The Makefile supports the following rules.

Rules intended for regular use

template: Build the moderncv template template.tex with LuaLaTeX. This rule can be called in one of two ways:
- make template: Build the template in casual style.
- make template STYLE=<style>: Build the template in the style specified by
  <style>. <style> can be classic, casual, banking, oldstyle or fancy.
templates: Build the template template.tex with LuaLaTeX for all moderncv styles and move resulting pdf files to the folder examples/.
userguide: Build the user manual manual/moderncv_userguide.tex with LuaLaTeX. This rule calls the rule templates before compiling the documentation.
clean: Clean the clutter created by compiling of the documents.
delete:Delete template.pdf and manual/moderncv_userguide.pdf.
deleteexamples: Delete examples/ folder and remaining template example pdf files in folder manual/.
force: Force rebuilding the user guide by running the rules delete deleteexamples userguide and clean `clean

Rules intended for package maintainers

version: Update the version information (version number and date) of all moderncv files (*.sty, moderncv.cls, *.tex). This rule can be called in two different ways. Note, however, that it is intended to be called by the rule release and usually does not need to be called explicitly.
- make version: Called in this way the version number is obtained through git describe --tags. If this information is newer all moderncv files get updated.
- make version NEW=<version number>: Optionally, the desired version number <version number> can be specified.
tarball: Create a new release tarball suitable for upload to CTAN. If the example/ folder is present, it gets included in the tar archive. Similary, all pdf files in the manual/ folder get included aswell. This rule is intended to be called by the rule release and usually does not need to be called explicitly.
release:Update the version information, rebuild examples as well as the user guide and create a releasable tarball including everything. In this way the tarball on CTAN contains ready made pdf files.

Discribe the make file rules and provide getting started information

…ual/ directory

stephanlachnit

Thanks for the work, please take a look at my comments.

.gitignore

README.md

stephanlachnit · 2021-04-30T20:13:56Z

Makefile

+tarball:
+	# build a tarball for release puposes. If the examples directory exist,
+	# include them
+	# remove existing tarballs
+	rm -f *.gz *.tar
+	# create tar with all files in git repo
+	git archive HEAD > $(TARBALL)
+	# remove git specific files
+	tar -f $(TARBALL) --delete .github/ .gitignore create-release-tarball.sh
+	# if examples exist include them in the tarball
+	if [[ -d "$(EXAMPLESDIR)" ]]; then
+		tar -rf $(TARBALL) --append $(EXAMPLESDIR)
+	fi
+	# include precompiled template pdfs and userguide from manual folder,
+	# the idea being that the userguide can be build from the manual folder
+	# and has everything that it needs to compile. If the release method gets
+	# called this ensures that a precompiled version of the userguide is
+	# included in the tar ball.
+	tar -rf $(TARBALL) --append $(MANUALDIR)
+	# compress
+	gzip $(TARBALL)


Ok first thing, with this you want to remove create-release-tarball.sh from the repo, as it is essentially the same. Second, the reason for the tarball is the upload to CTAN, so the example creating should be consistent. I personally don't think they should be included in the release tarball, only the manual.

The part where you add the manual should also be in the commit where the actual tarball will be added.

I thought it might be a good thing to have examples precompiled for users to have a look at. Therefore I included them.
To not clutter the repo with precompiled pdfs, I only included them in the release tar ball, so that they are also available on CTAN for download immediatelly.

Yes I agree that precompiled pdf shouldn't be in the repo. I checked a couple of other packages, and I guess it's fine if we add one example to the release tarball which can be linked to at the CTAN page (I wouldn't add all of them, I think that's a bit useless).

In any case, it's important that this is consistent, and not depending on the existence of a folder.

stephanlachnit · 2021-04-30T20:19:36Z

Makefile

+# user callable NEW option, to specify the new version. If unspecified, the
+# new version gets determined by git.
+ifdef NEW
+    VERSIONNEXT = $(NEW)
+else
+    VERSIONNEXT = $(shell git describe --tags --dirty)
+endif
+VERSIONDATENEXT = $(shell date +"%Y\/%m\/%d")


This is something I will comment later on, but I think this can be solved more elegantly.

See below, please remove this.

stephanlachnit · 2021-04-30T20:20:57Z

Makefile

+	lualatex $(MANUALTEX)
+	lualatex $(MANUALTEX)


Why not latexmk?

I have had issues in the past with latexmk, therefor I avoid it.

Can we go with latexmk? I think overall it is the better choice, since it does the rerunning automatically until all references are cleared. Maybe it's not perfect in every edge case, but here it should be fine.

We can also enforce lualatex: latexmk -pdflua $(MANUALTEX)

stephanlachnit · 2021-04-30T20:23:13Z

Makefile

+	# Upate version information and date of all moderncv files. A call make version
+	# will define VERSIONNEXT=$(shell git describe --tags). Alternatively, call
+	# "make version NEW=v5.13.298" to set v5.13.298 as the new version number.
+	# The date gets calculated by the date function.


Ok so this just doesn't work in this order. We first need to update the files, and then tag it via git. The other way round is completely useless (sorry). The version should be set by the user, and then git tagged.

No. This rule automates updating all files, that's the point. The makefile provides this method and the VERSION variable to make it easy to update all files in one go. From the explanation of the README:

version: Update the version information (version number and date) of all moderncv files (*.sty, moderncv.cls, *.tex). This rule can be called in two different ways. Note, however, that it is intended to be called by the rule release and usually does not need to be called explicitly.

make version: Called in this way the version number is obtained through git describe --tags. If this information is newer all moderncv files get updated.

make version NEW=<version number>: Optionally, the desired version number <version number> can be specified.

I first intended this rule to be called in the second way by the maintainer to first update all files as you said.
Then I thought it might be usefull to automate this with git, so that as a mainteiner you only need to run one command at the end and all information is up to date automatically.

I was intending to reduce your work load for releasing tarball to CTAN ;-)

make version: Called in this way the version number is obtained through git describe --tags. If this information is newer all moderncv files get updated.

Yes exactly that one doesn't make sense, since this will always be outdated. First the change of version number, then the git tag.

stephanlachnit · 2021-04-30T20:23:48Z

Makefile

+		rm -fv *.acn *.acr *.alg *.aux *.bcf *.blg *.dvi *.fdb_latexmk *.fls;
+		rm -fv *.glg *.idx *.ilg *.ist *.spl *.lof *.log *.lot *.out *.pdfsync;
+		rm -fv *.run.xml *.snm *.synctex.gz *.tdo *.toc *.vrb *blx.bib *~;


Why not latexmk -C?

as I said, I have had problem with latexmk

Please go with latexmk. It doesn't remove all the files, but to does this code (e.g. .bbl files are also generated when using biber).

manual/format_files_for_userguide.py

stephanlachnit · 2021-04-30T20:26:29Z

Btw can you update the CI workflow to build all?

stephanlachnit

Alright, I think I have now commented on everything that needs changing.

stephanlachnit · 2021-05-03T19:53:35Z

README.md

+```
+in a terminal. After completion of the compilation precompiled versions of the template in all styles can be found in the folder `examples` and 
+the user guide in the folder `manual`.  
+Alternatively get the tar ball from [CTAN](https://ctan.org/pkg/moderncv?lang=de). The examples as well as the documentation are already prebuilt in that tarball.


Url is in german, change it to https://ctan.org/pkg/moderncv

stephanlachnit · 2021-05-03T19:57:24Z

Makefile

+	lualatex $(MANUALTEX)
+	lualatex $(MANUALTEX)


Can we go with latexmk? I think overall it is the better choice, since it does the rerunning automatically until all references are cleared. Maybe it's not perfect in every edge case, but here it should be fine.

We can also enforce lualatex: latexmk -pdflua $(MANUALTEX)

stephanlachnit · 2021-05-03T20:12:01Z

Makefile

+		rm -fv *.acn *.acr *.alg *.aux *.bcf *.blg *.dvi *.fdb_latexmk *.fls;
+		rm -fv *.glg *.idx *.ilg *.ist *.spl *.lof *.log *.lot *.out *.pdfsync;
+		rm -fv *.run.xml *.snm *.synctex.gz *.tdo *.toc *.vrb *blx.bib *~;


Please go with latexmk. It doesn't remove all the files, but to does this code (e.g. .bbl files are also generated when using biber).

stephanlachnit · 2021-05-03T20:14:43Z

Makefile

+delete:
+	rm -fv $(TEMPLATEPDF)
+	rm -fv $(MANUALPDF)
+
+deleteexamples:
+	rm -rfv $(EXAMPLESDIR)
+	rm -fv $(MANUALDIR)/*.pdf


I guess we can merge these simply to delete, that should be enough. Also, delete should call clean.

stephanlachnit · 2021-05-03T20:15:18Z

Makefile

+	sed -i $$sedstring $(TEMPLATE)
+
+
+userguide: templates $(MANUAL)


It's called manual everywhere else, so let's change this to usermanual.

stephanlachnit · 2021-05-03T20:25:49Z

Makefile

+		# we need to split the $(VERSION) date format into substrings to using
+		# sed. This is due to / being a special character in sed.
+		YEAR=$(shell echo $(VERSIONDATE) | cut -d "/" -f 1)
+		MONTH=$(shell echo $(VERSIONDATE) | cut -d "/" -f 2)
+		DAY=$(shell echo $(VERSIONDATE) | cut -d "/" -f 3)
+		# update version info and date of *.sty, *.cls and *.tex files
+		# prepare find and replace with sed
+		findstr="$$YEAR\\/$$MONTH\\/$$DAY $(VERSION)"
+		replacestr="$(VERSIONDATENEXT) $(VERSIONNEXT)"


Ok I see now why you want to have the date in the makefile, but I still think this is not a particular good design. You can use this regex \d{4}\-\d{2}\-\d{2}\sv\d+.\d+.\d+ (via sed -E) to find the dates, and replace it with $(date -u -I) $(NEWVERSION)

Before, check if NEWVERSION is set, if not, then abort.

stephanlachnit · 2021-05-03T20:26:37Z

Makefile

+		# update VERSION and VERSIONDATE variable of this very file
+		sed -i "s/VERSION = $(VERSION)/VERSION = $(VERSIONNEXT)/g" $(MODERNCVDIR)/Makefile
+		findstr="VERSIONDATE = $$YEAR\\/$$MONTH\\/$$DAY"
+		replacestr="VERSIONDATE = $(shell date +"%Y")\\/$(shell date +"%m")\\/$(shell date +"%d")"
+		sed -i "s/$$findstr/$$replacestr/g" $(MODERNCVDIR)/Makefile
+		unset findstr; unset replacestr


With the comment mentioned above, it can be removed.

stephanlachnit · 2021-05-03T20:33:51Z

Makefile

+	rm -rfv $(EXAMPLESDIR)
+	rm -fv $(MANUALDIR)/*.pdf
+
+force:  delete deleteexamples userguide clean


I think just force is a bit ambiguous. Let's go with forcerebuild instead.

stephanlachnit · 2021-05-03T20:36:32Z

Makefile

+	# compress
+	gzip $(TARBALL)
+
+release: userguide version clean tarball


Here we would do delete (clean rebuild), version, then force (so we have the new version in the manual), then tarball and then do git commit -a -s -C $(NEWVERSION), then git tag -s HEAD~1 (I'll need to double if that git commit runs like that without prompting an editor, but that's the idea at least).

stephanlachnit · 2021-05-03T20:38:44Z

Makefile

+# user callable NEW option, to specify the new version. If unspecified, the
+# new version gets determined by git.
+ifdef NEW
+    VERSIONNEXT = $(NEW)
+else
+    VERSIONNEXT = $(shell git describe --tags --dirty)
+endif
+VERSIONDATENEXT = $(shell date +"%Y\/%m\/%d")


See below, please remove this.

cryptointerest · 2021-05-07T11:21:47Z

Thanks for all the comments. I will do as fast as I can, but I have some paper submission stuff etc. going on, so I'll have to see when I can work on it.

cryptointerest and others added 10 commits April 30, 2021 21:07

add Makefile to automate templete building and releases

c94015a

resolve conflicts

5af8ecb

Update README.md

b9b4cb3

Discribe the make file rules and provide getting started information

resovle gitignore conflict

72e99ae

make template rule aware of STYLE variable

68785bd

explain how to build template in a certain style

2709edc

update readme. include automatic version in title of user guide

8b38aaa

add python script to include known bugs into user guide

f156699

make userguide both compilable with make and from the file in the man…

bf7b6ed

…ual/ directory

resovle gitignore conflict

c118647

stephanlachnit requested changes Apr 30, 2021

View reviewed changes

David Seus added 4 commits April 30, 2021 22:51

remove kate-tmp and pdf from gitignore

235da0f

add notice back in as per review

9ef23be

remove *.gz from gitignore

f9d11fd

remove create-release-tarball.sh as per code review

6d54f74

stephanlachnit requested changes May 3, 2021

View reviewed changes

ShadowMitia mentioned this pull request Sep 6, 2022

Suggestion to clarify the manual #132

Closed

tianyizheng02 mentioned this pull request Jun 11, 2023

Update user guide #169

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce makefile #54

Introduce makefile #54

cryptointerest commented Apr 30, 2021

stephanlachnit left a comment

stephanlachnit Apr 30, 2021

cryptointerest Apr 30, 2021

stephanlachnit May 1, 2021

stephanlachnit Apr 30, 2021

stephanlachnit May 3, 2021

stephanlachnit Apr 30, 2021

cryptointerest Apr 30, 2021

stephanlachnit May 3, 2021

stephanlachnit Apr 30, 2021

cryptointerest Apr 30, 2021

cryptointerest Apr 30, 2021

stephanlachnit May 3, 2021

stephanlachnit Apr 30, 2021

cryptointerest Apr 30, 2021

stephanlachnit May 3, 2021

stephanlachnit commented Apr 30, 2021 •

edited

Loading

stephanlachnit left a comment

stephanlachnit May 3, 2021

stephanlachnit May 3, 2021

stephanlachnit May 3, 2021

stephanlachnit May 3, 2021

stephanlachnit May 3, 2021

stephanlachnit May 3, 2021

stephanlachnit May 3, 2021

stephanlachnit May 3, 2021

stephanlachnit May 3, 2021

stephanlachnit May 3, 2021

cryptointerest commented May 7, 2021

		sed -i $$sedstring $(TEMPLATE)


		userguide: templates $(MANUAL)

Introduce makefile #54

Are you sure you want to change the base?

Introduce makefile #54

Conversation

cryptointerest commented Apr 30, 2021

Makefile

Rules intended for regular use

Rules intended for package maintainers

stephanlachnit left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stephanlachnit commented Apr 30, 2021 • edited Loading

stephanlachnit left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cryptointerest commented May 7, 2021

stephanlachnit commented Apr 30, 2021 •

edited

Loading