search

davebalmer / joDoc

Simple, open-ended JavaScript source documentation system based on markdown. joDoc rev 1.0.1 is available. Check Wiki page for some examples.
http://joapp.com/jo#joDoc
Other
62 stars 4 forks source link

Multiple file output not supported #2

Closed davebalmer closed 13 years ago

davebalmer commented 13 years ago

Was thinking of the best way to handle filename generation for multiple files out. A few choices present themselves:

  1. filename in, filename out: regardless of the path a given file was pulled from, we use the filename.html for its output. Implication would be we couldn't have duplicate filenames in different paths, which I'm not 100% happy with.
  2. path munging: since it would be difficult to recreate directory trees for files from multiple sources, we could bake the path into a filename, like: ../js/core/myclass.js is output to a file named ___js_core_myclass.js. In this munging scheme, I'm replacing the . and / with underscores (in windows, would we replace the \ characters too?)
  3. first heading: we take the contents of the first <h1> tag we see in a file and use that as the filename, wikipedia style. From ../js/core/mylib.js we might get an output file like: MyLib.Core.html. And something more esoteric like README might become: Using_My_Lib.html (maybe lowercase everything, too?).

I think #3 may be the most useful, open to suggestion.

dfreedm commented 13 years ago

I'll do #3, but fall back to #1 if there are no h1 tags. Trying to figure out how to do autolinking correctly between multiple files.

davebalmer commented 13 years ago

The only danger with #3 is it might make it harder for users to keep solid bookmarks to pages if the filenames are subject to change along with heading text (or reordering within a given file). I think we should think about this a bit more, I'm leaning toward #2, but it has its issues as well (e.g. if the file folders get moved around, all the filenames get changed). Maybe we take a hybrid of #1, and add some unique addition to the filename (_01, _02, etc), and throw up a warning during the build. Seems like most cases simply using the same filename out as in (with extension change) would be fine.

dfreedm commented 13 years ago

Sounds good. And it will make autolinking much easier between files.

davebalmer commented 13 years ago

Not sure I'm happy about keeping the directory structure. What happens with files outside the directory where jodoc was run (e.g. ../../src or /usr/src/blahblah/)?

davebalmer commented 13 years ago

Going with the filename-munger approach, not 100% sure about the munging scheme (all the underscores look awkward), but it sure does work. Closing for now.