Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
tiborsimon committed Jul 7, 2016
1 parent 29da0a3 commit 08890b6
Showing 1 changed file with 34 additions and 50 deletions.
84 changes: 34 additions & 50 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
[![PyPI](https://img.shields.io/pypi/dm/projects.svg?maxAge=2592000)](https://pypi.python.org/pypi?name=projects&version=0.1.1&:action=display)
[![Status](https://img.shields.io/badge/status-under_development-yellow.svg)]()

__projects__ is an easy to use _project navigator_ and a Makefile-like _scripting engine_. You can define your commands and inline documentations in _Projectfiles_.
__projects__ is an easy to use _project navigator_ and a Makefile-like _scripting engine_. You can define your commands and inline documentations in __Projectfiles__.

It works on every UNIX system with Python (2.7+ 3.x) installed. It's main purpose is to provide a simpler scripting interface with a built in documentation system. It's main target is any open source projects that want to be more user friendly from the first use. __projects__ designed to minimize the typing.

Expand All @@ -17,7 +17,7 @@ __projects__ is not a replacement for Makefile or CMake it is an optional wrappe
## Features

- quick project navigation
- _Projectfile_ based recursive scripting system
- __Projectfile__ based recursive scripting system
- instant help menu generation

## Installation
Expand Down Expand Up @@ -60,26 +60,22 @@ This command is the main trigger for projects. It behaves differently depending

_OUTSIDE_ your projects directory, it opens the project selector screen, where you can select your project by typing the projects name or by using the arrows keys.

_INSIDE_ any of your projects (inside the repository root directory) this command will show the manual generated from the _Projectfiles_.
_INSIDE_ any of your projects (inside the repository root directory) this command will show the manual generated from the __Projectfiles__.


### Direct project selector command

```
p p
```
`p p`

This command behaves the same as the previous `p` command but it will always display the project selector screen. This could be handy if you want to switch projects quickly.

This is the only prohibited command name that you cannot use for your commands.

### Execute defined command

```
p <command>
```
`p <command>`

This is the command for executing commands defined in the _Projectfiles_. By convention all defined command should start with an alphanumeric character. The commands started with a dash reserved for __projects__ itself.
This is the command for executing commands defined in the __Projectfiles__. By convention all defined command should start with an alphanumeric character. The commands started with a dash reserved for __projects__ itself.

The `<command>` keyword can be anything except the already taken keywords:

Expand All @@ -88,60 +84,48 @@ The `<command>` keyword can be anything except the already taken keywords:

### Help screen

```
p (-h|--help)
```
`p (-h|--help)`

Brings up this help screen.

### Version information

```
p (-v|--version)
```
`p (-v|--version)`

Prints out the current __projects__ version.

### Template Projectfile
### Template Projectfile generation

```
p (-i|--init)
```
`p (-i|--init)`

Generates a template _Projectfile_ into the current directory.
Generates a template __Projectfile__ into the current directory.

### Projectfile walk order listing

```
p (-w|--walk)
```
`p (-w|--walk)`

Lists out all directories in your project in the walk order __projects__ will follow. It marks the directories that contain a _Projectfile_.
Lists out all directories in your project in the walk order __projects__ will follow. It marks the directories that contain a __Projectfile__.

### Processed command script listing

```
p (-l|--list) <command>
```
`p (-l|--list) <command>`

Lists out the processed command bodies for the given command.

### Markdown generation

```
p (-md|--markdown) [<file_name>]
```
`p (-md|--markdown) [<file_name>]`

Generates a Markdown file from your processed _Projectfiles_. You can optionally specify a name for teh generated file. The default name is README.md.
Generates a Markdown file from your processed __Projectfiles__. You can optionally specify a name for teh generated file. The default name is README.md.


# Projectfile

_Projectfiles_ are the files you create in order to define commands that will be executed with the `p <command>`. _Projectfiles_ provide a powerful and self explanatory way to interact with your project.
__Projectfiles__ are the files you create in order to define commands that will be executed with the `p <command>`. __Projectfiles__ provide a powerful and self explanatory way to interact with your project.

You can create an example _Projectfile_ with the `p (-i|--init)` command. The generated _Projectfile_ will demonstrate all provided functionality except the recursive command concatenation since it will generate only one _Projectfile_.
You can create an example __Projectfile__ with the `p (-i|--init)` command. The generated __Projectfile__ will demonstrate all provided functionality except the recursive command concatenation since it will generate only one __Projectfile__.

There are mandatory and optional features you can add to _Projectfile_.
There are mandatory and optional features you can add to __Projectfile__.

#### Mandatory

Expand Down Expand Up @@ -175,9 +159,9 @@ v1.0.0
...
```

This feature will define the earliest version that is compatible with the used _Projectfile_ format. All __projects__ versions greater or equal to the defined one will be compatible with the format, but earlier versions may have problems with future features. The first release version is v1.0.0.
This feature will define the earliest version that is compatible with the used __Projectfile__ format. All __projects__ versions greater or equal to the defined one will be compatible with the format, but earlier versions may have problems with future features. The first release version is v1.0.0.

If there are more _Projectfiles_ in your project and the defined versions are different, the smallest version will be used to maximize the functionality.
If there are more __Projectfiles__ in your project and the defined versions are different, the smallest version will be used to maximize the functionality.


#### main description [optional]
Expand All @@ -192,7 +176,7 @@ Description for the whole project.

After the version you can define a global description of the whole project. You can write long lines, __projects__ will wrap them according to the defined `doc-width` key in the __~/.prc__ configuration file. Single line breaks won't break the lines in the generated manual. You have to use an empty line in order to add a line break.

If you have multiple _Projectfiles_ created, the main descriptions will be concatenated with empty lines according to the walk order.
If you have multiple __Projectfiles__ created, the main descriptions will be concatenated with empty lines according to the walk order.


#### variables [optional]
Expand All @@ -216,7 +200,7 @@ ${{variable}}

Both escapement is interpreted equally.

Defined variables go to the global variable pool. You cannot assign a variable the more than once. Hence you cannot redefine a variable in a later _Projectfile_ (a _Projectfile_ is the file that is processed later according to the walk order). Redefining a variable will raise an error. Since every variables go to the global variable pool, you can use the variables in any _Projectfile_ independently which _Projectfile_ you defined them. It is possible to use a variable in the root level _Projectfile_ that is defined in a later _Projectfile_.
Defined variables go to the global variable pool. You cannot assign a variable the more than once. Hence you cannot redefine a variable in a later __Projectfile__ (a __Projectfile__ is the file that is processed later according to the walk order). Redefining a variable will raise an error. Since every variables go to the global variable pool, you can use the variables in any __Projectfile__ independently which __Projectfile__ you defined them. It is possible to use a variable in the root level __Projectfile__ that is defined in a later __Projectfile__.


#### command header [mandatory]
Expand All @@ -236,7 +220,7 @@ According to the given example you can invoke your command with the following sy

Both will execute the same command body after the dependent commands (dependency1 and dependency2) is executed first in the given order.

A command cannot be redefined in the same _Projectfile_ twice. If you redefine a command in another _Projectfile_, the commands' bodies will be appended to each other according to the path relationship of these files.
A command cannot be redefined in the same __Projectfile__ twice. If you redefine a command in another __Projectfile__, the commands' bodies will be appended to each other according to the path relationship of these files.


#### command description [optional]
Expand All @@ -251,7 +235,7 @@ my_command:

The command description will be added to the generated manual. It behaves the same as the main description, except it requires an indentation in any way (space, tab, count doesn't matter).

If a command is redefined in another _Projectfile_, the command descriptions will be appended according to the path relationship of these files.
If a command is redefined in another __Projectfile__, the command descriptions will be appended according to the path relationship of these files.


#### command body [mandatory]
Expand All @@ -270,7 +254,7 @@ The command body defines what commands __projects__ needs to execute if you invo

Simple example

If you have multiple _Projectfiles_ in your project and there are command headers that are defined in more than one _Projectfile_, the command bodies will be appended according to the path relationship of these files.
If you have multiple __Projectfiles__ in your project and there are command headers that are defined in more than one __Projectfile__, the command bodies will be appended according to the path relationship of these files.

```
╔═══════════════════════════════════╦═══════════════════════════════════╗
Expand Down Expand Up @@ -299,21 +283,21 @@ If you have multiple _Projectfiles_ in your project and there are command header

- You can use the `(-w|--walk)` and `(-l|--list)` commands to get information about the commands will be executed by __projects__.
- The command listing shows that the command bodies were concatenated according to the walk order (you can check with the `(-w|--walk)` command).
- The concatenated command list contains directory change commands (cd) so every command defined in a _Projectfile_ gets executed in the same directory level as it's _Projectfile's_ directory level.
- The concatenated command list contains directory change commands (cd) so every command defined in a __Projectfile__ gets executed in the same directory level as it's __Projectfile's__ directory level.
- Thus the directory change commands, you can notice that each command will execute in the same execution context regardless of the command's length (number of lines). This is different than the Makefile conventions, and provide a much more simpler script writing.


### More complex example

There is another feature that can be used to execute post configuration eg. executing commands after all lower order command bodies were executed. This feature is called recursive separator (`===`). If you place this separator inside a command's body, and there are other lower level _Projectfiles_ in your project, the command bodies will be appended in a special, recursive order.
There is another feature that can be used to execute post configuration eg. executing commands after all lower order command bodies were executed. This feature is called recursive separator (`===`). If you place this separator inside a command's body, and there are other lower level __Projectfiles__ in your project, the command bodies will be appended in a special, recursive order.

In a _Projectfile_, all commands before the separator are called the __pre__ commands, and all the commands after the separator are called the __post__ commands. The seprator in every command body is optional. If there is no separator, all the command lines in the command body will be handled as a __pre__ command block. Similarly if the command body starts with a separator the whole body will be used as a post block.
In a __Projectfile__, all commands before the separator are called the __pre__ commands, and all the commands after the separator are called the __post__ commands. The seprator in every command body is optional. If there is no separator, all the command lines in the command body will be handled as a __pre__ command block. Similarly if the command body starts with a separator the whole body will be used as a post block.

If there are no lower level _Projectfiles_, and you have a command with separated body, the sepration will be ignored.
If there are no lower level __Projectfiles__, and you have a command with separated body, the sepration will be ignored.

If you have lower level _Projectfiles_, the base level pre commands will be executed first then the execution will jump to the lower level _Projectfile_. After the lower level _Projectfile's_ command script gets executed, the execution will be jump back after the base level separator, and the base post block will be executed.
If you have lower level __Projectfiles__, the base level pre commands will be executed first then the execution will jump to the lower level __Projectfile__. After the lower level __Projectfile's__ command script gets executed, the execution will be jump back after the base level separator, and the base post block will be executed.

If the lower level _Projectfile_ has separated command bodies, and there are yet another lower level _Projectfile_, the execution will jump down recursively until the last possible separation is executed.
If the lower level __Projectfile__ has separated command bodies, and there are yet another lower level __Projectfile__, the execution will jump down recursively until the last possible separation is executed.

The following example will demonstrate this behavior:

Expand Down Expand Up @@ -379,10 +363,10 @@ The following example will demonstrate this behavior:
#### What you can notice in this example

- The recursive separators works as described. The post commands are executed after the pre commands for that level and all the recursive lower level other commands executed.
- Commands get executed in the same level where the _Projectfile_ they are defined in is located.
- Commands get executed in the same level where the __Projectfile__ they are defined in is located.
- Automatic directory changing command insertion is smart enough to insert only the absolute necessary directory changing commands. If there are no lower level commands, but the recursive separator exists, no directory changing will be inserted before the post commands. If there are no pre commands, no directory cahnging will be happen before the recursive separator content. Same goes to the post commands. If there are no post commands, no directory changing commands will be inserted after the recursive separator's content is executed.

TIP: You can always create a template _Projectfile_ with the `(-i|--init)` command.
TIP: You can always create a template __Projectfile__ with the `(-i|--init)` command.


## License
Expand Down

0 comments on commit 08890b6

Please sign in to comment.