Research/LaTeX-proposal
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #49 from slel/patch-1

Browse Source 
Improve README formatting
This commit is contained in:
Michael Kohlhase 2020-08-24 12:45:35 +02:00 committed by GitHub
commit a8382a2970
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 97 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
README.md
View File

@ -6,7 +6,7 @@ coordinate the process via a source code control system like Git or Subversion,
the proposal writing team to concentrate on the contents rather than the mechanics of the proposal writing team to concentrate on the contents rather than the mechanics of
wrangling with text fragments and revisions. In fact the proposal package has evolved out wrangling with text fragments and revisions. In fact the proposal package has evolved out
of a series of collaborative proposal writing efforts, where large teams (up to 30 of a series of collaborative proposal writing efforts, where large teams (up to 30
individuals from up to 20 sites) have written a 100- page proposal in three weeks (with individuals from up to 20 sites) have written a 100-page proposal in three weeks (with
over 2000 commits). Such collaborative writing sprints are impossible without a revision over 2000 commits). Such collaborative writing sprints are impossible without a revision
control system and a “semantic” document class that generates tables, charts, and control system and a “semantic” document class that generates tables, charts, and
deliverable lists from content markup and thus takes care of many of the routine tasks of deliverable lists from content markup and thus takes care of many of the routine tasks of
@ -18,11 +18,11 @@ In the simplest case, just clone the repository, and extend your `TEXINPUTS`
environment variable so that it can find it. On a UNIX system something like the following environment variable so that it can find it. On a UNIX system something like the following
should work. should work.
``` ```
cd /path/to/your/project cd /path/to/project
git clone https://github.com/KWARC/LaTeX-proposal git clone https://github.com/KWARC/LaTeX-proposal
echo 'export TEXINPUTS = "$(TEXINPUTS):/path/to/your/project/LaTeX-proposal//:"' >> ~/.bashrc echo 'export TEXINPUTS = "$(TEXINPUTS):/path/to/project/LaTeX-proposal//:"' >> ~/.bashrc
``` ```
Of course you will have to replace `/path/to/your/project` with a path appropriate to Of course you will have to replace `/path/to/project` with a path appropriate to
your system. A simple `git pull` will update you to the newest version. your system. A simple `git pull` will update you to the newest version.
## Getting Started with a New Proposal ## Getting Started with a New Proposal
@ -34,16 +34,14 @@ the three variables in the upper section of the `Makefile` accordingly, if you w
a revision control system for a larger group, read (far) below. a revision control system for a larger group, read (far) below.
Here is what you would do on a UNIX system after the initial steps above to prepare a DFG Here is what you would do on a UNIX system after the initial steps above to prepare a DFG
proposal (or an EU proposal the same setup works as well, but with suitably adapted proposal (for an EU proposal the same setup works as well, but with suitably adapted
paths). paths).
``` ```
cp examples/dfg/proposal . cp examples/dfg/proposal .
sed -i .bak s/PROP.dir = ..\/..\/..\//Prop.dir = ./ proposal/Makefile sed -i .bak s/PROP.dir = ..\/..\/..\//Prop.dir = ./ proposal/Makefile
sed -i .bak s/BIB = ..\/lib/BIB = ./ proposal/Makefile sed -i .bak s/BIB = ..\/lib/BIB = ./ proposal/Makefile
``` ```
## Disclaimer ## Disclaimer
The LaTeX proposal class has been developed to "scratch my own itch" over many proposals The LaTeX proposal class has been developed to "scratch my own itch" over many proposals
@ -56,14 +54,14 @@ me and saves me (and my friends who use it) a lot of work.
## License ## License
The proposal class is distributed under the terms of the LaTeX Project Public License from The proposal class is distributed under the terms of the LaTeX Project Public License from
CTAN archives in directory macros/latex/base/lppl.txt. Either version 1.0 or, at your CTAN archives, see the file `macros/latex/base/lppl.txt` at CTAN, either version 1.0 or, at your
option, any later version. option, any later version.
## Help wanted; submit issues, feature requests, & pull requests ## Help wanted: submit issues, feature requests, pull requests
As this is just a side project for me, please submit issues and feature requests to the As this is just a side project for me, please submit issues and feature requests to the
[issue tracker](issues). Even better, improve the code and submit a [issue tracker](issues). Even better, improve the code and submit a
[pull request](https://help.github.com/articles/about-pull-requests/) [pull request](https://help.github.com/articles/about-pull-requests/).
## Repository Layout ## Repository Layout
@ -77,10 +75,10 @@ specialized to particular funding bodies that have their own styles.
* `examples`: example proposal (stubs). * `examples`: example proposal (stubs).
* `etc`: style files from the sTeX bundle added for convenience (only on GitHub, not on CTAN) * `etc`: style files from the sTeX bundle added for convenience (only on GitHub, not on CTAN)
* `lib`: Makefiles for the management of self-documenting packages * `lib`: Makefiles for the management of self-documenting packages
* `bin`: utilities, e.g. a script that makes GitHub issues from the deliverables of a proposal for project managment if the proposal is granted. * `bin`: utilities, e.g. a script that makes GitHub issues from the deliverables of a proposal for project management if the proposal is granted.
# Using this repo in a paper repository ## Using this repo in a paper repository
The best way to write a collaborative proposal is to use a revision control system. It is The best way to write a collaborative proposal is to use a revision control system. It is
usually a good idea to make this repository into an external sub-repository that can be usually a good idea to make this repository into an external sub-repository that can be
@ -88,59 +86,111 @@ updated as necessary. In the instructions below we assume that you - as the pape
maintainer - want to add the proposal classes as a sub-repository at path maintainer - want to add the proposal classes as a sub-repository at path
`lib/LaTeX-proposal` from the top of the paper repository. `lib/LaTeX-proposal` from the top of the paper repository.
## The best way for GIT ### The best way for Git
is via the `git-subrepo` extension of `git`. Unfortunately this is not part of git is via the `git-subrepo` extension of `git`. Unfortunately this is not part of Git
(yet). So you as the paper repos maintainer have to (yet). So you as the paper repos maintainer have to
[install it first](https://github.com/git-commands/git-subrepo#readme) if you want to [install it first](https://github.com/git-commands/git-subrepo#readme) if you want to
install the proposal classes as a subrepos. Your users do not, they will get the subrepos install the proposal classes as a subrepos. Your users do not, they will get the subrepos
automatically on `git clone` or `git pull`. automatically on `git clone` or `git pull`.
1. go to the top of your paper prehistory: `cd path/to/top` (you can only make a 1. go to the top of your paper prehistory:
"subrepo" from there) ```
2. add the LaTeX-proposal distribution repos as a "subrepo": `git subrepo clone git@github.com:KWARC/LaTeX-proposal.git LaTeX-proposal` cd /path/to/top
```
(you can only make a"subrepo" from there)
2. add the LaTeX-proposal distribution repos as a "subrepo":
```
git subrepo clone git@github.com:KWARC/LaTeX-proposal.git LaTeX-proposal
```
Note that under `git-subrepo` the "external" is not updated automatically, a Note that under `git-subrepo` the "external" is not updated automatically, a
maintainer has to "pull" it. This can be seen as a feature and not a bug (there is less of maintainer has to "pull" it. This can be seen as a feature and not a bug (there is less of
a chance to break things). a chance to break things).
1. go to the top of your paper repository: `cd path/to/top` (you can only pull from there) 1. go to the top of your paper repository:
2. pull the proposal classes repos as a "subrepo": `git subrepo pull LaTeX-proposal` ```
cd /path/to/top
```
(you can only pull from there)
2. pull the proposal classes repos as a "subrepo":
```
git subrepo pull LaTeX-proposal
```
To contribute changes back to the the LaTeX-proposal repository, you analogously do To contribute changes back to the the LaTeX-proposal repository, you analogously do
1. go to the top of your paper prehistory: `cd path/to/top` (you can only push from there) 1. go to the top of your paper prehistory:
2. do the push: `git subrepo push LaTeX-proposal` ```
cd /path/to/top
```
(you can only push from there)
2. do the push:
```
git subrepo push LaTeX-proposal
```
easypeasy! Easypeasy!
### The second best way for Git
## The second best way for GIT
is via `git subtree`. is via `git subtree`.
1. go to the top of your paper repository: `cd path/to/top` 1. go to the top of your paper repository:
2. add the LaTeX-proposal repos as a remote: `git remote add LaTeX-proposal ```
git@github.com:KWARC/LaTeX-proposal.git` under the name `LaTex-proposal`. cd /path/to/top
3. add the remote `LaTeX-proposal` as a subtree: `git subtree add --prefix=LaTeX-proposal LaTeX-proposal master --squash` ```
2. add the LaTeX-proposal repos as a remote:
```
git remote add LaTeX-proposal git@github.com:KWARC/LaTeX-proposal.git
```
under the name `LaTex-proposal`.
3. add the remote `LaTeX-proposal` as a subtree:
```
git subtree add --prefix=LaTeX-proposal LaTeX-proposal master --squash
```
(here under the path `LaTeX-proposal`). The `--squash` reduces history noise. (here under the path `LaTeX-proposal`). The `--squash` reduces history noise.
When you want to update the subrepository to the newest version, you have to "subtree When you want to update the subrepository to the newest version, you have to "subtree
pull" as above: pull" as below:
1. go to the top of your paper repository: `cd path/to/top` 1. go to the top of your paper repository:
2. subtree-pull: `git subtree pull --prefix=LaTeX-proposal LaTeX-proposal master --squash` ```
this is a bit inconvenient, but works well. cd /path/to/top
```
2. subtree-pull:
```
git subtree pull --prefix=LaTeX-proposal LaTeX-proposal master --squash
```
This is a bit inconvenient, but works well.
Contributing back to the LaTeX-proposal repository is somewhat more complex; RTFM! Contributing back to the LaTeX-proposal repository is somewhat more complex; RTFM!
## Externals in SVN ### Externals in SVN
In a subversion repository you can must make an external by
1. go to the top of your paper prehistory: `cd path/to/top` In a Subversion repository you must make an external by
2. make the `lib` subdir if necessary: `mkdir lib`
3. add the external: `svn propedit svn:externals lib` 1. go to the top of your paper prehistory:
4. an editor will appear, add the line `LaTeX-proposal LaTeX-proposal https://github.com/KWARC/LaTeX-proposal/trunk` ```
5. commit your work: `svn commit -m'adding external for the LaTeX-proposal '` cd /path/to/top
```
2. make the `lib` subdir if necessary:
```
mkdir lib
```
3. add the external:
```
svn propedit svn:externals lib
```
4. an editor will appear, add the line
```
LaTeX-proposal LaTeX-proposal https://github.com/KWARC/LaTeX-proposal/trunk
```
5. commit your work:
```
svn commit -m 'adding external for the LaTeX-proposal'
```
Note that in SVN any `svn update`@ will update the LaTeX-proposal repository in the Note that in SVN any `svn update`@ will update the LaTeX-proposal repository in the
external as well. external as well.