search

firemodels / fds

Fire Dynamics Simulator
https://pages.nist.gov/fds-smv/
Other
668 stars 625 forks source link

Add a short tutorial to the FDS guides #9582

Open emanuelegissi opened 3 years ago

emanuelegissi commented 3 years ago

As proposed last time we met in the US, I have been thinking of addressing the issue of novice users impacting on the huge and complex FDS users' guide. The same questions keep repeating on the discussion group.

I played a little with the idea of adding a short tutorial doc to the existing FDS guides.

By using the \usepackage{catchfilebetweentags} LaTeX package it is possible to automatically copy paste tagged text from the other guides into the tutorial. So, once set up, the tutorial should be 90% self updating.

I attach an example of what I mean and a proposed content structure.

This proposal is 99% self contained. The only modification to the other guides would be adding tags for text to be copied like this:

%*<tut:tag1>
Text to be copy-pasted
%/<tut:tag1>

The inserted tags are LaTeX comments, so no interference there.

I can contribute the tutorial, based on a previous doc I wrote and training experience.

emanuelegissi commented 3 years ago

Here is the link: https://drive.google.com/drive/folders/1_kDrv8UNshqSqL0QP2cqVFQ57r0R1FV0?usp=sharing

mcgratta commented 3 years ago

The link requires permission.

emanuelegissi commented 3 years ago

Sorry, should work now

On Mon, Jun 21, 2021, 17:12 Kevin McGrattan @.***> wrote:

The link requires permisssion.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/firemodels/fds/issues/9582#issuecomment-865114191, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACXMVYZ3Q5G66ILWU2OQVPTTT5JEZANCNFSM47BYQV3Q .

mcgratta commented 3 months ago

I am looking at old issues and it appears that this one fell through the cracks. I blame the pandemic.

The link above no longer works. Is there another example somewhere of how this could work?

emanuelegissi commented 3 months ago

In fact at the time I had tried experimenting with copy-pasting the text from the UG into an hypothetic tutorial, but the resulting text did not come out very well. You had to make a much too many edits and adaptations. So I thought that it would be easier to just write it from scratch as a wiki, to lower the barrier to new contributions and maintenance.

Currently I would suggest going with something like: Github + Jekyll with continuous integration.

I suggest the Just the docs Jekyll template, that supports Latex equations and Mermaid diagrams out of the box.