From 725e8c910f14f3f87d1e97023efe214313edf3af Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Thu, 8 Feb 2018 00:51:46 +0100 Subject: Adding title and description also mentioned in README.md The first commit didn't have an explanation on correcting the title of the project in the final PDF or the top-level Makefile, so a pointer was added to the list. Also, some extra dependencies were removed from `README' and its paragraphs were scaled to the new width of 75 characters that is defined in `.dir-locals.el' (for Emacs settings, taken from Gnuastro). --- README.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 1a52571..ae67e0e 100644 --- a/README.md +++ b/README.md @@ -131,11 +131,13 @@ been explained here), please let us know to correct it. ```shell $ git clone https://gitlab.com/makhlaghi/reproduction-pipeline-template.git + $ mv reproduction-pipeline-template your-project-name + $ cd your-project-name ``` - **Copyright**, **name** and **date**: Go over the following files and correct the copyright, names and dates in their first few lines: - `README`, `Makefile` and `reproduce/src/make/*.mk`. When making new + `configure`, `Makefile` and `reproduce/src/make/*.mk`. When making new files, always remember to add a similar copyright statement at the top of the tile. @@ -177,6 +179,14 @@ been explained here), please let us know to correct it. $ git commit # Make your first commit (mention the first output) ``` + - **Title**, **Short description** of project: In this raw skeleton, the + title or short descripton of your project should be added in the + following two files: `Makefile` (the first line), and + `tex/preamble-style.tex` (the last few lines, along with the names of + you and your colleagues). In both cases, the texts you should replace + are all in capital letters to make them easier to identify. + + - **`README`**: Go through this top-level instruction file and make it fit to your pipeline: update the text and etc. Don't forget that your colleagues or anyone else, will first be drawn to read this file, so @@ -184,6 +194,7 @@ been explained here), please let us know to correct it. work. Therefore, also check and update `README` one last time when you are ready to publish your work (and its reproduction pipeline). + - **First input dataset**: The user manages the top-level directory of the input data through the variables set in `reproduce/config/pipeline/DIRECTORIES.mk.in` (the user actually edits @@ -291,6 +302,16 @@ way, we can add it here for others to also benefit. recipe or rule. As a general rule of thumb: first the comments, then the code. + - *File title*: In general, it is good practice to start all files with + a single line description of what that particular file does. If + further information about the totality of the file is necessary, add + it after a blank line. This will help a fast inspection where you + don't care about the details, but just want to remember/see what that + file is for. This information must ofcourse be commented (its for a + human), but this is kept separate from the general recommendation on + comments, because this is a comment for the whole file, not each step + within it. + - **Make programming**: Here are some experiences that we have come to learn over the years in using Make and are useful/handy in research -- cgit v1.2.1