Latex documentation

[jloizu]

I made some changes in the source regarding the latex documentation. Usually, I go to

https://w3.pppl.gov/~shudson/Spec/subroutines.html

to have a look at the documentation, which I think is compiled from the source. How is this updated according to the new source? Or perhaps the better question is: how to I compile the source so that it generates the documentation in my local repository?

Sorry for my ignorance.

[zhucaoxiang]

Hi Joaquim,

I will give a quick reply by phone first.

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

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 think I did this quite a long time ago and forgot to update that website. I can help do it if you have any questions.

On Jul 25, 2018, at 4:27 AM, Joaquim notifications@github.com wrote:

I made some changes in the source regarding the latex documentation. Usually, I go to

https://w3.pppl.gov/~shudson/Spec/subroutines.html

to have a look at the documentation, which I think is compiled from the source. How is this updated according to the new source? Or perhaps the better question is: how to I compile the source so that it generates the documentation in my local repository?

Sorry for my ignorance.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[SRHudson]

Hi,

In my Makefile, I have some instructions for constructing the online documentation, which I have included below. I fully agree that any of us should be able to update the documentation, and that perhaps the documentation should be kept somewhere other than my own webpage.

pdfs: $(addsuffix .pdf,$(HFILES)) head.html ifeq ($(USER),shudson) cat head.html > $(WEBDIR)/Spec/subroutines.html for file in $(HFILES) ; do cp $${file}.pdf $(WEBDIR)/Spec/. ; grep "!title" $${file}.h | cut -c 7- | \ awk -v file=$${file} -F!\ '{print "<a href="file".pdf\">"file""$$1""$$2""}' \

$(WEBDIR)/Spec/subroutines.html ; \ done echo "" >> $(WEBDIR)/Spec/subroutines.html endif

Regards, Stuart

---

Dr. Stuart R. Hudson Deputy Head, Theory Department, Princeton Plasma Physics Laboratory P.O. Box 451, Princeton NJ 08543, USA phone +1 (609) 243 2631 , fax +1 (609) 243 2662 shudson@pppl.gov , http://theory.pppl.gov/

On Wed, Jul 25, 2018 at 4:27 AM, Joaquim notifications@github.com wrote:

I made some changes in the source regarding the latex documentation. Usually, I go to

https://w3.pppl.gov/~shudson/Spec/subroutines.html

to have a look at the documentation, which I think is compiled from the source. How is this updated according to the new source? Or perhaps the better question is: how to I compile the source so that it generates the documentation in my local repository?

Sorry for my ignorance.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/PrincetonUniversity/SPEC/issues/43, or mute the thread https://github.com/notifications/unsubscribe-auth/ALB7OaKn_h4IHK-HNdcmhc-XZD6997Imks5uKCvXgaJpZM4Vfphh .

[jloizu]

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.

[zhucaoxiang]

@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.

[jloizu]

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?

[SRHudson]

Hi,

Presently, as Joaquim says, when I enter "make pdfs", the documentation on my personal website is updated.

It should be the case that anyone can update the documentation on the repository website.

Regards, Stuart

---

Dr. Stuart R. Hudson Deputy Head, Theory Department, Princeton Plasma Physics Laboratory P.O. Box 451, Princeton NJ 08543, USA phone +1 (609) 243 2631 , fax +1 (609) 243 2662 shudson@pppl.gov , http://theory.pppl.gov/

On Thu, Jul 26, 2018 at 5:02 AM, Joaquim notifications@github.com wrote:

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

1. 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/ https://princetonuniversity.github.io/SPEC/ right? Maybe it should be the case that he also updates automatically in the general website. Stuart?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/PrincetonUniversity/SPEC/issues/43#issuecomment-408029355, or mute the thread https://github.com/notifications/unsubscribe-auth/ALB7Od-1Oi5YUdvitA6m3xvyjpWMt6Pcks5uKYWzgaJpZM4Vfphh .

[zhucaoxiang]

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.

[jloizu]

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 ?

[zhucaoxiang]

@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.

[jloizu]

If I typels --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?

[lazersos]

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.

[jloizu]

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

[lazersos]

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

[zhucaoxiang]

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.

[jloizu]

@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.

[zhucaoxiang]

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

[jloizu]

@zhucaoxiang that worked, thanks! Closing this issue.