Diff being reverted:
diff --git a/ref/software_guidelines.mdwn b/ref/software_guidelines.mdwn index fa015d6..b86494b 100644 --- a/ref/software_guidelines.mdwn +++ b/ref/software_guidelines.mdwn @@ -6,8 +6,570 @@ Downloadable versions: [[TXT|ipol-swg.txt]] [[PDF|ipol-swg.pdf]] Previous versions: [[archives|archives]] -Next version: [[drafts|drafts]] --- +<!-- JL: it doesn't work !!?? [[!inline pagenames="ipol-swg.html" feeds="no" raw="yes"]] + +--> + +<!-- workaround: copy mkdwn file below --> + +IPOL reviews, uses, publishes and distributes some software provided by +the authors. With the requirements and recommendations expressed in +these guidelines, we intend to facilitate the production and review of +verifiable and usable software for reproducible research. + +[[!toc levels=2]] + + +\setcounter{secnumdepth}{0} + +# In Brief: Check List, Check Service and Examples + +The list hereafter is a summary of the guidelines, to quickly check a +program. Some are requirements, others are only recommendations. +This document details and explains the guidelines later. + +- zip or tar/gzip archive `name_version.{zip,tar.gz,tgz}` +- everything into a `name_version/` folder +- file names with `a-z`,`A-Z`,`0-9`,`-`,`_`,`.` +- no hidden file, backup or useless file, no binary +- portable code, 32/64-bits, nothing specific to an operating system +- command-line non-interactive interface +- approx. 30 s computation in the demo environment +- copyright attribution and GPL/BSD license info in every source file +- patent warning if needed +- `README.txt` essential information +- correct, clean code in English +- `main()`, algorithmic and auxiliary code in different files +- detailed comments for every function and every implementation step +- example input data and result + + +# About this Document + +## Status + +This document is the official IPOL Software Guidelines, version +1.04, published on May 14th, 2018. It is immediately applicable +and obsoletes previous versions. The reference version is available +at <https://tools.ipol.im/wiki/ref/software_guidelines/>. + +## Revisions + +When needed, future versions of this document will be published and will +replace the current version. The current version will still be +available, with a summary of the differences. This revision will be +announced on [the IPOL website](http://www.ipol.im/) and [the IPOL +discussion list](http://tools.ipol.im/mailman/listinfo/discuss). + +Changes from version 1.02: + +- Removed restrictions regarding exclusive use of C code. +- Changed restrictions on the size of uploaded files. + +## Vocabulary + +These guidelines are designed for a research journal whose articles +include some software material. They are written for IPOL, but may be +used by others. + +In this document, the term "published software" designates +the reference software implementation of an algorithm submitted for +publication in a journal article. The "web demo" is an online facility +used to test this software. An article **may** contain more than one +software, and a demo **may** use more than one software. + +In this document, the words **must**, **must not**, **should**, +**should not**, **recommended**, and **may** are used to express +required, recommended, and optional +items. [IETF RFC2119](http://tools.ietf.org/html/rfc2119) describes +their interpretation, and Annex A adds details in the context of these +guidelines. + +## License + +This document is licensed under a +[CC-BY License](http://creativecommons.org/licenses/by/3.0/). It can +be freely reused and modified as long as its origin is +credited. Modified versions must be mentioned as such and not +misrepresented as the original IPOL version. + +# Guidelines + +## 1. Packaging and Content + +### 1.1. Compressed Archive + +A published software **must** be packaged as a compressed archive +file. This file archive can either be a single volume .ZIP compressed +archive or a GZIP compressed tar archive[^tar]. In the remainder +of this document, we will use the terms "zip archive" and "tar/gzip +archive" for convenience. + +[^tar]: These file formats are defined by [the PKZIP APPNOTE + specification](http://www.pkware.com/documents/casestudies/APPNOTE.TXT), + version 6.3.2, for the .ZIP compressed archive format, [the IETF + RFC1952](http://tools.ietf.org/html/rfc1952) for the GZIP compressed + format, and [the POSIX.1 ustar + definition](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_06) + for the tar archive format. + +Annex B of this document provides some examples of programs that can +be used to produce such compressed archives. + +### 1.2. Archive Name, Program Name and Version + +The compressed archive file of a published software **must** be named +according to the `name_version.extension` pattern, where: + +- `name` and `version` **must** consist only of lower case letters + (`a-z`), digits (`0-9`), minus (`-`) and period (`.`) signs; +- `name` **must** indicate the name of the program; this name can + be the name of the executable program file, or another name, at the + author's will; +- `version` **must** start with a digit; it **must** indicate a + version number for the program, in the sense that two different + releases of the program **must** have two different version numbers; + if no version numbering scheme is established for the program, the + `YYYYMMDD` pattern based on the year, month and day of the release + date **may** be used; +- `extension` **must** be `zip` for zip archives and `tar.gz` or `tgz` + for tar/gzip archives. + +### 1.3. File and Folder Names + +All the files and folders extracted from the compressed archive **must** +be located inside a base folder named `name_version`, where `name` and +`version` are identical to those used for the compressed archive file +name. Absolute path **must not** be used for files and folders extracted +from the archive. + +The name of all files and folders composing the published software +**must** consist only of lower or upper case letters (`a-z`, `A-Z`), +digits (`0-9`), minus (`-`), underscore (`_`) and period (`.`) +signs. They **should** start with a letter. + +The names **should** provide a meaningful hint of the content of these +files and folders. + +### 1.4. Hidden and Useless Files + +A published software **should not** include hidden files or folders or +by-products of the tools used by the authors, such as (but not limited +to): + +- files inserted by file managers (`.DS_Store`, `.directory`); +- folders inserted by version control managers (`.svn`, `.git`); +- backup versions (`filename~`, `filename.bak`). + +The software **should not** be distributed with files not useful to +build, use or study the implementation of the algorithm published in +the journal. + +## 2. Implementation + +### 2.1. Source Code + +A published software **must** include all the material necessary to +build one or more executable program files implementing the algorithm +published in the journal. This material **must** be provided in +human-readable source code form. A published software **must not** be +distributed with binary precompiled files if these files can be +obtained from source code[^bin]. + +[^bin]: If the authors want to distribute binary versions, they can do it + in the journal as supplementary material but not via the + compressed archive of the published software covered by these + guidelines. + +Annex C provides some information for the authors to help them +perform some frequent implementation tasks. + +### 2.2. Programming Language + +The source code of a published software **must** follow the published +standard syntax of one or more programming languages. + +### 2.3. Portability + +The source code of a published software **must not** require any +extension of the language or its standard library, or any resource