File naming convention

[David Bovill]

Thanks for the notes everyone....


On 25 January 2011 18:50, Calvin Waterbury <cjw at eml.cc> wrote:

> The first thing to understand about Windows® file names you can't use the
> following...
>
> \ / : * ? " < > |
>

:( I thought the pipe character was OK nowadays?

Hmmm... so it seems "." is fine for folders... I wander if urlencoding has a
place here?

On 25 January 2011 20:10, Jeff Massung <massung at gmail.com> wrote:

> On Tue, Jan 25, 2011 at 6:11 AM, David Bovill <david at vaudevillecourt.tv
> >wrote:
>
> - Use a database to map from source file -> documentation. This way no hack
> is needed and it mitigates future problems, like what happens when someone
> goes back and renames hello.txt to hello_world.txt?
>

Renaming will be a major issue - but a database is not an easy option...

- Don't have a "docs" folder, but instead make the documentation file sit
> right next to the source file.
>

nor is this set up unfortunately (that is how I have the files at the
moment, but I have to move them into their own folder as the web server
insists on it.

The only solution therefore is a simple function which can be in JavaScript
or LiveCode.

- Multiple files w/ the same name in different locations
>

This should be OK - as the documentation tree will mimic the file tree.


> - Renaming source files (documentation "link" now broken)
> - Moving of source files to a new location ("link" broken)
>

These are the headaches. One thought I've had is to use the revision control
system to trace the files version back to it's original root, and use this
as an ID - but this is too complicated and not available in the simplified
environment I'm using - I'm stuck with a simple function...

Thanks for raising the issues though - will need some thought. A couple of
possibilities give some hope with regard to creating a robust solution:

   1. I can use the commit messages (ie revision log information) regarding
   renames and deletions and apply these to the documentation at a convenient
   time.
   2. I can use the sha1 hash of the file as generated by the revision
   control system and embed this in the initial documentation - if a link gets
   broken, I can always trace the documentation back to this file via the hash.