Latex documentation about spec HOT 17 CLOSED

from spec.

from spec.

Thanks for the replies.

1. Type ‘make pdfs’, and can you compile all the pdfs correctly?

It seems to work (I get a bunch of pdfs compiled and consistent with my documentation updates) although at the end it gives this message,

make: *** No rule to make target 'head.html', needed by 'pdfs'. Stop.

does this mean something is not working or is that normal?

2. Instead of putting all the documentations at Stuart’s directory, you can track all the documentations in the branch ‘gh-pages’ and it will automatically show on the website https://princetonuniversity.github.io/SPEC/subroutines.html

I don't know what do you mean by tracking the documentations in the branch gh-pages.
Also, I tried to access the website you mentioned and I get error 404.

Now I am thinking that perhaps this head.html error in the pdf compilation is related to where one wants to upload the documents online, right? As in Stuart's makefile.

from spec.

@jloizu @SRHudson

I made some changes in Makefile to automatically do all the steps. Please pull and check.

I'm not quite sure if we should put all the commands in the Makefile. Maybe it's better to type it manually. There are circumstances that these auto commands can cause errors, for example if you are not working on master, there is no meaning to checkout back to master and revert your stashing changes. Also it might cause problems if your master branch is already clean, in that case it will recover your last stashing changes which is not we need. You can decide whatever you like, but I think these commands should give you enough instructions to do it manually.

I also push some changes in README.md, and there will be some links to the documentations(https://princetonuniversity.github.io/SPEC/). Actually, you can also put tutorials, flow chart, plotting script instructions on that website. Just FYI, you can look at FOCUS website (https://princetonuniversity.github.io/FOCUS/). Honestly, it's still under construction.

from spec.

Thanks Caoxiang, it seems to work for me, I just have some small issues with this:

1. When I do make pdfs, at the very end I get this message:

git stash pop
No stash found.
Makefile:311: recipe for target 'pdfs' failed
make: *** [pdfs] Error 1

2. If I understand correctly, when Stuart does now make pdfs it will only update the documentation on his personal website, but not on https://princetonuniversity.github.io/SPEC/ right? Maybe it should be the case that he also updates automatically in the general website. Stuart?

from spec.

from spec.

1. Errors for make pdfs

git stash pop
No stash found.
Makefile:311: recipe for target 'pdfs' failed
make: *** [pdfs] Error 1

This is because you have a clean master branch before you checkout gh-pages. That's expected.

2. Stuart's personal website.
   I talked to Stuart this morning. He agreed that we can just keep one public website for SPEC. So I will edit the Makefile and delete the if user=shudson stuffs.

I have made changes in the new branch docs, please pull and check.

from spec.

I think now the Latex documentation editing and updating is (thanks to @zhucaoxiang) well built in the compilation.

In case of significant changes in the documentation, it would be good that we somehow alert the rest of users when performing changes, so that they can read the newly changed parts and perhaps give feedback. Otherwise it is going to become hard to follow if everyone starts modifying the documentation. Any particular suggestion, @SRHudson ?

from spec.

@jloizu There is actually one more small flaw. If your operating system, such as OSX, doesn't support the command ls --full-time, the modified time will not be captured. So do your compiled pdfs. You can view the last line on the bottom of each documentation.

from spec.

If I type ls --full-time in my terminal, I get

drwxr-xr-x 3 loizu spc-th 4096 2018-06-11 12:47:00.287760918 +0200 Sandboxes
drwxr-xr-x 4 loizu spc-th 4096 2018-07-26 17:24:41.293013183 +0200 spec

which seems to work and provide year,month,day,hour,etc... but maybe it is not to be interpreted as in other operating systems?

from spec.

This depends on which distribution provides ls. The BSD version does not support --full-time but the GNU version does. For the sake of compatibility I would suggest using ls -lT.

from spec.

I guess you mean ls -lt (if I type ls -lT it does not recognize it)

from spec.

@jloizu, so apparently there is no good fix. Because in BSD it's ls -lT but in GNU it's ls --full-time.

from spec.

I agree. There are no good solutions. Probably, the one who want to update the documentations could be aware of his operating system and customize the following command. Use ls --full-time, or ls -lT, or ls -lt and change the exact position 35-53 to capture the correct data info.

@ls --full-time ../$*.h | cut -c 35-53 > .$*.date ; \

The only left issue is the awk warning. It's not urgent. We can fix it later.

from spec.

@zhucaoxiang Sorry to bother again with this...but it's been a long time since we last discussed it and I have the feeling that we have not solved the issue.

For example, I just merged some changes into master and in those changes there is also some additional documentation information (namely explaining what inifactor is in preset.h). When I do make pdfs locally on my repository, I can generate the correct updated pdf documentation. But on the links to the documentation available on GIT, the pdfs remain the same. How can we update those as well?

Thanks and sorry for my ignorance on the subject.

from spec.

@jloizu try make publish. If it's not working, please let me know.

from spec.

@zhucaoxiang that worked, thanks! Closing this issue.

from spec.