Hi, all, As most of you certainly know by now, the JSON docs have been under active development in Google Docs since September:
https://docs.google.com/document/d/1fXViveNhDbiXgCuE7QDXQOKeFzf2qNUkBEgiUvoqFN4/view That they're in GDocs, as opposed to fossil, has always simply been a matter of convenience. i like to write docs when i get bored and i can do that from anywhere with gdocs. The long-term plan has always been to port them into fossil (somewhere) once they settle down a bit. The API is now at the point that i would like to move the docs somewhere with a friendlier, less transient URL, but i'm not at all certain how i'd like to do it. That's what i'm looking for opinions on... The considerations which have come to mind so far: - i would prefer to keep it in wiki form, as opposed to embedded docs, because i often write docs from arbitrary locations. - i would prefer to not use fossil's wiki markup (i find it too verbose - too close to HTML), but Google Code (it's what i know and like best). i could _possibly_ be convinced to use Markdown if there are _compelling_ arguments for it in this specific context (not in a generic sense). (But please don't turn this thread into the re-re-re-visited wiki format debate!) - Because of the size of the docs (currently over 50 pages, which would need to be split up into many wiki pages) and the frequency at which i tend to update docs, i'd prefer to keep them out of the core fossil repo (to avoid polluting it, basically), but... - It might be interesting to kick around the idea of adding json.fossil-scm.org (Richard willing) and host the docs from there using a custom JSON-based front-end like the one i've started porting my own wikis to: http://fossil.wanderinghorse.net/wikis/whio/?page=whio (that's an HTML5/JS app on top of a fossil wiki, using the Google Code syntax) Such a subdomain could also house code specific to the JSON API, like script language wrappers and demo apps. (Alternately, i could host it on fossill.wanderinghorse.net.) While we could argue forever about the down-side of the non-googlability of client-side-rendered wikis, i think it is important that that the documentation for the JSON API be served via the JSON API, if for no other reason than having it as the canonical demonstration app. As i am famously narrow-sighted, i'm quite certain there are angles and considerations i've not thought of. i'd be much appreciative for any input regarding how best to set up/organize/maintain the JSON-related docs in the mid- to long-term. On my local machine i've set up a wiki repo where i've started porting in the GDocs, but i'm not committed to that approach at this point (just experimenting with the structure). Using a wiki has the down-side of not being able to remove/move/rename pages, but OTOH a custom client can filter the page list however it likes, so we could still keep obsoleted pages out of a user's immediate view. :-? -- ----- stephan beal http://wanderinghorse.net/home/stephan/ http://gplus.to/sgbeal
_______________________________________________ fossil-users mailing list [email protected] http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
