Skip to content

Commit

Permalink
experimenting with one-line-per-sentence in README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@glyphobet
glyphobet committed Jun 17, 2012
1 parent 81564b3 commit a4bddbf
Showing 1 changed file with 57 additions and 17 deletions.
74 changes: 57 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,63 +1,97 @@
Fragments
=========

Fragments uses concepts from version control to replace many uses of templating languages. Instead of a templating language, it provides diff-based templating; instead of revision control, it provides "fragmentation control".
Fragments uses concepts from version control to replace many uses of templating languages.
Instead of a templating language, it provides diff-based templating;
instead of revision control, it provides "fragmentation control".

Fragments is a [DRY (Don't Repeat Yourself)](http://en.wikipedia.org/wiki/Don't_repeat_yourself) violation manager; it is a [Multiple Source of Truth](http://en.wikipedia.org/wiki/Single_Source_of_Truth) engine.
Fragments is a [DRY (Don't Repeat Yourself)](http://en.wikipedia.org/wiki/Don't_repeat_yourself) violation manager;
it is a [Multiple Source of Truth](http://en.wikipedia.org/wiki/Single_Source_of_Truth) engine.

What is diff-based templating?
------------------------------

Generating HTML with templating languages is difficult because templating languages often have two semi-incompatible purposes. The first purpose is managing common HTML elements & structure: headers, sidebars, and footers; across multiple templates. This is sometimes called page "inheritance". The second purpose is to perform idiosyncratic display logic on data coming from another source. When these two purposes can be separated, templates can be much simpler.
Generating HTML with templating languages is difficult because templating languages often have two semi-incompatible purposes.
The first purpose is managing common HTML elements & structure: headers, sidebars, and footers; across multiple templates.
This is sometimes called page "inheritance".
The second purpose is to perform idiosyncratic display logic on data coming from another source.
When these two purposes can be separated, templates can be much simpler.

Fragments manages this first purpose, common HTML elements and structure, with diff and merge algorithms. The actual display logic is left to your application, or to a templating language whose templates are themselves managed by Fragments.
Fragments manages this first purpose, common HTML elements and structure, with diff and merge algorithms.
The actual display logic is left to your application, or to a templating language whose templates are themselves managed by Fragments.

What is fragmentation control?
------------------------------

The machinery to manage common and different code fragments across multiple versions of _a single file_ already exists in modern version control systems. Fragments adapts these tools to manage common and different versions of _several different files_.
The machinery to manage common and different code fragments across multiple versions of _a single file_ already exists in modern version control systems.
Fragments adapts these tools to manage common and different versions of _several different files_.

Each file is in effect its own "branch", and whenever you modify a file ("branch") you can apply ("merge") that change into whichever other files ("branches") you choose. In this sense Fragments is a different kind of "source control"--rather than controlling versions/revisions over time, it controls fragments across many files that all exist simultaneously. Hence the term "fragmentation control".
Each file is in effect its own "branch", and whenever you modify a file ("branch") you can apply ("merge") that change into whichever other files ("branches") you choose.
In this sense Fragments is a different kind of "source control"--rather than controlling versions/revisions over time, it controls fragments across many files that all exist simultaneously.
Hence the term "fragmentation control".

As I am a linguist, I have to point out that the distinction between [Synchronic](http://en.wikipedia.org/wiki/Synchronic_analysis) and [Diachronic](http://en.wikipedia.org/wiki/Diachronics) Linguistics gave me this idea in the first place.

How does it work?
-----------------

The merge algorithm is a version of [Precise Codeville Merge](http://revctrl.org/PreciseCodevilleMerge) modified to support cherry-picking. Precise Codeville Merge was chosen because it supports [accidental clean merges](http://revctrl.org/AccidentalCleanMerge) and [convergence](http://revctrl.org/Convergence). That is, if two files are independently modified in the same way, they merge together cleanly. This makes adding new files easy; use Fragment's `fork` command to create a new file based on other files (or just `cp` one of your files), change it as desired, and commit it. Subsequent changes to any un-modified, common sections, in that file or in its siblings, will be applicable across the rest of the repository.
The merge algorithm is a version of [Precise Codeville Merge](http://revctrl.org/PreciseCodevilleMerge) modified to support cherry-picking.
Precise Codeville Merge was chosen because it supports [accidental clean merges](http://revctrl.org/AccidentalCleanMerge) and [convergence](http://revctrl.org/Convergence).
That is, if two files are independently modified in the same way, they merge together cleanly.
This makes adding new files easy; use Fragment's `fork` command to create a new file based on other files (or just `cp` one of your files), change it as desired, and commit it.
Subsequent changes to any un-modified, common sections, in that file or in its siblings, will be applicable across the rest of the repository.

Like version control, you run Fragments on the command line each time you make a change to your HTML, not before each page render.

What is it good for?
--------------------

Fragments was designed with the task of simplifying large collections of HTML or HTML templates. It could replace simpler CMS-managed websites with pure static HTML. It could also handle several different translations of an HTML website, ensuring that the same HTML structure was wrapped around each translation of the content.
Fragments was designed with the task of simplifying large collections of HTML or HTML templates.
It could replace simpler CMS-managed websites with pure static HTML.
It could also handle several different translations of an HTML website, ensuring that the same HTML structure was wrapped around each translation of the content.

But Fragments is also not HTML specific. If it's got newlines, Fragments can manage it. That means XML, CSS, JSON, YAML, or source code from any programming language where newlines are common (sorry, Perl). cFragments is even smart enough to know not to merge totally different files together. You could use it to manage a large set of configuration files for different servers and deployment configurations, for example. Or you could use it to manage bug fixes to that mess of duplicated source files on that legacy project you wish you didn't have to maintain.
But Fragments is also not HTML specific.
If it's got newlines, Fragments can manage it.
That means XML, CSS, JSON, YAML, or source code from any programming language where newlines are common (sorry, Perl).
cFragments is even smart enough to know not to merge totally different files together.
You could use it to manage a large set of configuration files for different servers and deployment configurations, for example.
Or you could use it to manage bug fixes to that mess of duplicated source files on that legacy project you wish you didn't have to maintain.

In short, Fragments can be used anyplace where you have thought to yourself "this group of files really is violating DRY".

Integration with version control
--------------------------------

Fragments has no history; It only stores the previous committed state of a file. Storing history is up to your version control system. But Fragments stores its repository configuration in such a way to allow your version control system to manage it painlessly and obviously. Configuration is stored in a `_fragments` directory. This directory name is not preceded by a `.`, and all the files in it are stored as plain text. The configuration resides one directory above your actual content, so it does not interfere with template loading code, and so it is not accidentally deployed to production along with your actual content.
Fragments has no history; It only stores the previous committed state of a file.
Storing history is up to your version control system.
But Fragments stores its repository configuration in such a way to allow your version control system to manage it painlessly and obviously.
Configuration is stored in a `_fragments` directory.
This directory name is not preceded by a `.`, and all the files in it are stored as plain text.
The configuration resides one directory above your actual content, so it does not interfere with template loading code, and so it is not accidentally deployed to production along with your actual content.

The `rename` and `forget` commands in Fragments are written to not interfere with a version control's rename and remove commands, as these commands sometimes need to be used in tandem.

Invisibility
------------

Fragments is invisible to people who don't know it's being used. If you (or someone else) make more than one change to a file, Fragments' `apply` command allows you to perform chunk-based interactive application of changes, similar to `git commit --patch` or `hg record`. So, you can give a single HTML file to your web designer or junior programmer, let him or her modify it as desired, and later, selectively apply some of those changes across all other HTML files, while leaving other changes only in the modified file.
Fragments is invisible to people who don't know it's being used.
If you (or someone else) make more than one change to a file, Fragments' `apply` command allows you to perform chunk-based interactive application of changes, similar to `git commit --patch` or `hg record`.
So, you can give a single HTML file to your web designer or junior programmer, let him or her modify it as desired.
Later, you can selectively apply some of those changes across all other HTML files, while leaving other changes only in the modified file.

Installation
------------

Fragments is [on PyPI](http://pypi.python.org/pypi/fragments). You can install it with `pip install fragments`.
Fragments is [on PyPI](http://pypi.python.org/pypi/fragments).
You can install it with `pip install fragments`.

Usage
-----

Fragments installs a `fragments` command line script. Like version control, the first argument to Fragments is the command. And like version control, you must first `$ fragments init` a repository, then `$ fragments follow` some files, then `$ fragments commit` them. I deliberately chose different command names in some cases, to remind you that Fragments is not version control.
Fragments installs a `fragments` command line script.
Like version control, the first argument to Fragments is the command.
And like version control, you must first `$ fragments init` a repository, then `$ fragments follow` some files, then `$ fragments commit` them.
Deliberately different command names are used in some cases, to remind you that Fragments is not version control.

Commands
--------
Expand All @@ -68,7 +102,8 @@ Commands

* `init [FRAGMENTS_ROOT]`

Initialize a new fragments repository. Repository is in a directory named `_fragments/`, created in either the current working directory, or _FRAGMENTS\_ROOT_ if specified.
Initialize a new fragments repository.
Repository is in a directory named `_fragments/`, created in either the current working directory, or _FRAGMENTS\_ROOT_ if specified.

* `status [[ -l | --limit] STATUS ] [FILENAME [FILENAME ...]]`

Expand Down Expand Up @@ -135,9 +170,12 @@ Future improvements

### Preprocessors

Since Fragments is diff-based, it will not do well with minified or otherwise compressed content. Do not expect it to handle changes to your 10,000 character, single line, über-compressed CSS or JavaScript file, or to the inline JavaScript function in an `onclick` attribute in your HTML. The more newlines there are in your files, the more robust Fragments' merging will be.
Since Fragments is diff-based, it will not do well with minified or otherwise compressed content.
Do not expect it to handle changes to your 10,000 character, single line, über-compressed CSS or JavaScript file, or to the inline JavaScript function in an `onclick` attribute in your HTML.
The more newlines there are in your files, the more robust Fragments' merging will be.

Adding preprocessors to enforce consistent newline placement and indentation across all followed files would potentially make Fragments' merging even more robust. The preprocessors would run before `commit`, `fork`, and `apply`, and there would be different preprocessors for different file formats.
Adding preprocessors to enforce consistent newline placement and indentation across all followed files would potentially make Fragments' merging even more robust.
The preprocessors would run before `commit`, `fork`, and `apply`, and there would be different preprocessors for different file formats.

### Miscellaneous improvements

Expand All @@ -149,4 +187,6 @@ Adding preprocessors to enforce consistent newline placement and indentation acr
Credits
-------

Fragments is Copyright 2012 by Matt Chisholm, and is released under the BSD License. It is available [on GitHub](https://github.com/glyphobet/fragments) and [on PyPI](http://pypi.python.org/pypi/fragments). Many thanks to Ross Cohen for his thoughts on the idea, and for preparing Precise Codeville Merge for use in Fragments.
Fragments is Copyright 2012 by Matt Chisholm, and is released under the BSD License.
It is available [on GitHub](https://github.com/glyphobet/fragments) and [on PyPI](http://pypi.python.org/pypi/fragments).
Many thanks to Ross Cohen for his thoughts on the idea, and for preparing Precise Codeville Merge for use in Fragments.

0 comments on commit a4bddbf

Please sign in to comment.