Source folder structure
SqueeG opened this issue · 19 comments
Hey everyone,
When making changes to the Tome use the top-level 'src' folder.
The v0.7 and v0.6 folders are legacy folders. :)
Sorry if that confused you. :(
We should not import their structure. We should start with a clean slate, using our own structure. It might end up similar to theirs in some places, but only if that's the actually best way to organize things.
Basically, the AwesomeTome skips past any part of the book that doesn't have tome updates to it, but we're putting in every single part of the book as well as tome updates. That's enough changes that it's easier to start from scratch. Unless the main LaTeX writer for the current project is going to be the main LaTeX writer from the AwesomeTome project (which doesn't currently appear to be the case).
Yeah, and we still need to hammer out what's in and what's not, but that's probably something for the forum topic.
That's a slightly different issue.
My point is this : ignore the legacy folders. All changes are to be made in the top level src folder.
I'd like to see an updated structure that better matches the eventual book layout. A structure that hides files you don't immediately care about when you're working on a section seems like a nice thing IMO. So probably a directory for each chapter, with subdirectories for things like classes by specific authors and feat types and whatever else.
Honestly doing folders in folders seems a lot more complex than simply having all base classes in a base class folder.
PDF structure/layout is completely divorced from the underlying file structure. If you wanted to append author names to cladses... that could work. That way you could just filter by name using a simple search.
It was aimed at keeping it more obviously modular, but it's also not a big deal if it's not in.
Well that was sort of my point. Right now each file is it's own topic and you create coherent sections by creating a file FOR that section that draws from the smaller articles.
Like Lokathor mentioned in the thread, you can have a classes chapter file in a "chapters" folder and that file pulls in the classes which are in the "classes" folder.
Unless I'm misunderstanding you I think you were mixing presentation structure with code/data/file.structure.
No, I'm sort of trying to mix those on purpose to make it easier for people to find things that they care about in a way they may be more familiar with. We could dump all the files in the sea (read: C:, to make a root joke) for all the code cares, but that doesn't help contributors find things they want and ignore things they don't quickly. The author thing is probably farther than it needs to go to keep file structure from hindering contributors, but a folder per chapter to keep things more contained is probably needed. For reference, I kind of want a file per skill or per feat type (if not per actual feat) to make it possible to farm out small contributions and reduce delays from people getting large sections back slowly. 4 people working on individual skills one skill at a time (with a skill format template or example) can get them done more quickly and flexibly than 1 person working on the whole section... and also leaves our project more interesting to people who want different skills included in the final doc. And that amount of file generation seems like it would benefit from better folder containment.
So instead of chapter5:feats being some explanatory text and a list of included files from folder/feats; and chap6:skills being the same except a list of includes from folder/skills... what would we be looking at?
Because I agree with keepjng things in bite sized chunks. That keeps things much simpler. I'm just not seeing the disconnect.
No, that's about what we'd be looking at on the code side, though I'd push the intro text into its own included file even. And I'd want to rework some existing things that aren't in that format already (like feats) so they matched that setup, but only if we needed to edit them anyway because it's not priority work.
The file structure thing is just because I don't see a reason to not do it. I'm talking about a lot more files for people to sort though in order to get that bite sizeiness, and chunking helps people find things and reduces barriers to contribution slightly. It also makes the code structure more obvious to write. The disconnect is maybe that you think I'm conflating the code and file structure for no reason, when I'm actually suggesting that they should look the same because I see benefits in mirroring the structure on both sides.
In terms of making it easy to be modular and for others to use it later in different ways, the file structure actually should match the PDF's structure as closely as possible. So, all the base classes are in a "base-classes" directory and then all those get pulled into the "Base Classes" chapter of the book, etc. Because people are going to be reading the PDF first, and then looking for where the LaTeX for a part of the PDF is.
Since this is all in source control, can we just tag the current commit as "v0.6", "v0.7", and "awesomeTome", then delete everything and start with a clean slate?
You mean delete the legacy folders completely?
Yeah. They're in version control, so if anybody wants to use them they can just check out the appropriate tag, and it sounds like we're going to be starting over and they're just clutter.
Deleting everything seems a bit much, since we have a lot of useable content. Better to just make a new folder for the tomeSRD structure, delete everything but the src folder (which has copies for formatting and whatever) and start porting things into new folder as they're completed.
Yeah, I can do that once we, you know, hammer down more about what content is in or out. As we go along, things that get put into the "current" version can have their "old" version deleted, and once an old section is empty we can delete that file or folder.
As much as we make a big deal about how this is a Tome thing, the SRD itself is still the majority of the compiled work, and so we'll end up largely sticking things onto the SRD rather than the other way around, because almost nothing in the Tomes is a total overhaul for any system.
So, we're going to have Chapters. That's just how books work. Each chapter will have sections and sub-sections and so on, that's how LaTeX works and it makes Tables of Contents easy to figure out. Any given material in the book is only likely to show up a single time, in the area of the book appropriate to it. Given all these facts, I'd say that each chapter should have a folder, and that items within that chapter should be kept within that folder. If there's enough within a chapter to justify it then we can have folders within a chapter folder (eg: feats come in more than one type, if we put each feat in its own file we might want to have one folder per feat category).
Yes, file structure, code structure, and output structure should all be heavily influenced by one another in a thing like this. This is not a computer program of nebulous parts floating around in an abstract machine of some sort, there's very clear results with a LaTeX project in terms of what you feed the compiler and what you get in your PDF output. When people want to modify the project, and they want to change something in Chapter 3, there should be a chapter 3 file or folder in the file structure for them to find and then open up to see how chapter 3 is written. There's no reason to have a "chapters" folder and a "base classes" folder. Every base class is in the "base classes" chapter, so just do that. Every skill entry is in the "skill entries" chapter, so just do that. Etc.
Well, crap. Saw this after I'd deleted some folders, renamed some folders, and added new folders for the struct (which don't seem to have been uploaded because I don't know why). Suppose I could have waited a bit longer until things were hammered out, but people have been asking for text stuff to work on and I've been suggesting things, so it seemed like something that should be sorted sooner rather than later.
Edit - folders require files in them to be seen by Git. So it's there now, and can be renamed however we want.
I put my existing SRD stuff into git, and now that I know more of what I'm doing in terms of using git I can do more of this tomorrow.
Essentially however, we need to shift some of the discussion topics from being discussion towards being pass/fail or yes/no checklists of what we are and aren't doing, and what we already do have and what we will need to create. Then we can begin moving forward in a more serious way.
Pretty much, yeah.
But with the folder structure updated, legacy and SRD files ready for merging, and the older copies removed, I think we can call this issue closed.