While trying to generate CGE documentation I get ./mk_docs.sh: line 137: pasdoc: command not found even if I copy pasdoc to this folder. I've downloaded Linux version of pasdoc, but it doesn't provide any means of installation - just a standalone application. There are 2 files pasdoc_gui and pasdoc in the bin folder and doc folder with license and other similar files. While pasdoc_gui works fine pasdoc says "cannot execute binary file". pasdoc_gui requires some .pds file as a preset, which isn't available for Castle Game Engine.
Maybe console-version pasdoc it is 32 bit only?
pasdocs_gui works perfectly for me and I've successfully generated docs for my game :) But generating Castle Game Engine documentation requires much more settings which is not "just copy" to pasdocs_gui.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
(Sorry for the delay in answering, I took a short vacation:) I'm back now, and will answer everything as I go through my backlog:)
The PasDoc release doesn't provide any means of installing it, we just let you unpack it anywhere and (optionally) make your environment variable $PATH contain the bin/ subdirectory. On Linux, you can e.g. add something like
export PATH="$PATH:$HOME/installed/pasdoc/bin"
to your .bashrc.
On Debian or Ubuntu or derivatives, you may also find a pasdoc package:)
In Castle Game Engine:
The script mk_docs.sh assumes that you have already set your $PATH as needed, and it simply runs "pasdoc", which means that the binary "pasdoc" is searched on $PATH (but not in the current directory, this is how Unix shells always behave, they do not implicitly search the current directory).
Indeed, we don't provide a .pds file for pasdoc_gui. It would duplicate the information from mk_docs.sh, and mk_docs.sh is a little more flexible.
So, the remaining problem is: why does (non-gui) pasdoc say "cannot execute binary file" on your system? For this, I don't know the answer yet... On https://sourceforge.net/projects/pasdoc/files/ , you can download either 64 or 32 version for Linux. If you get the correct one, it should work. What is weird: both pasdoc and pasdoc_gui are either compiled 64bit or 32bit (I double-checked it now), so they should either both fail or both work. You can test what is binary architecture by "file .../bin/pasdoc" in console, it should say "ELF 64-bit LSB executable" or "ELF 32-bit LSB executable", and it should of course match your system:)
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I've downloaded pasdoc-0.14.0-linux-x86_64.tar.gz file, so it should be 64 bits. And both bin files appear to be 64 bits. Namely:
...pasdoc/bin$ file pasdoc
pasdoc: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, for GNU/Linux 2.4.0, not stripped
...pasdoc/bin$ file pasdoc_gui
pasdoc_gui: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.4.0, stripped
...pasdoc/bin$ dir -1 -l
total 10136
-rwxrwxrwx 1 eugene root 2283896 Aug 16 2015 pasdoc
-rwxrwxrwx 1 eugene root 8091056 Aug 16 2015 pasdoc_gui
...pasdoc/bin$ bash pasdoc
pasdoc: pasdoc: cannot execute binary file
...pasdoc/bin$ pasdoc
bash: pasdoc: command not found
Works the same way under ROOT. The file is located at NTFS file system, but it doesn't work if copied to native EXT3 (i.e. Linux home folder) either.
P.S. Oddly, pasdoc_gui also tells the same thing "cannot execute" in console, however, it still works fine if I doubleclick-execute it from file manager (Thunar).
The Unix shells do not automatically search for the specified program in the current directory. They only search the things on your $PATH environment variable.
So (if you have not yet set your $PATH environment variable to include "...pasdoc/bin") then doing
pasdoc
answers "command not found" because it cannot find "pasdoc" on $PATH.
To execute the binary in the current directory, you must provide the directory explicitly, e.g. by "./" prefix. This will work:
As for why "bash pasdoc" fails: using "bash xxx" is a way to execute bash scripts, not a binary program. It answers "cannot execute binary file", to tell you that the binary file was unexpected --- it expected a text file (shell script).
It's not about 32-bit vs 64-bit. "bash xxx" cannot execute any binary file.
Double-clicking on a program works, because Thunar executes it correctly (depends on the implementation, but most likely it doesn't use shell to execute the program at all).
Thunar actually executes both console and GUI programs, they both work, but when you run console "pasdoc' then nothing is shown (the output goes to a special file "/home/michalis/.xsession-errors"; unlike from Windows, on Linux you will not get a "blinking" terminal window if you execute a console command by double-clicking).
All this is related to how Unix and Unix shells work, you can reproduce this with any program on your system, compiled with FPC or not. This is
not related to pasdoc
not related to 32 vs 64-bit,
not related to pasdoc vs pasdoc_gui,
not related to NTFS vs EXT3 :)
If you would install pasdoc from the Debian package, then it would be already available on $PATH (Debian package would place the pasdoc binary in /usr/bin). So running "pasdoc" would work. (But not because "pasdoc" binary was different! Only because it would be already installed on $PATH.)
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Ooops... My bad as usually :) I was absolutely sure I always ran executables this way... But now I recall all of those had some sort of their own .sh script to start.
Thanks a lot and sorry for disturbing you.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Thanks a lot again! After installing a Debian package everything works. I'm using pasdoc_0.14.0-1_amd64.deb from the Debian repository which looks like the latest version.
I get a lot of similar warnings like:
Warning[1]: Tag "groupbegin" is not implemented yet, ignoring (in description of "CastleSceneCore.TCastleSceneCore.SetTime")
Warning[1]: Tag "groupend" is not implemented yet, ignoring (in description of "CastleSceneCore.TCastleSceneCore.IncreaseTimeTick")
and
Warning[1]: Could not resolve link "EConvertError" (from description of "CastleXMLConfig.TCastleConfig.GetBoolean")
and a final error
if which inkscape > /dev/null; then \
inkscape ../logo/castle_game_engine_icon.svg \
--export-width=256 \
--export-height=256 \
--export-background=white \
--export-background-opacity=255 \
--export-png=html/castle_game_engine_icon.png \
; else cp /media/VST/CGE/castle-engine../cge-www/htdocs/images/castle_game_engine_icon.png html/; fi
cp: cannot stat ‘/media/VST/CGE/castle-engine../cge-www/htdocs/images/castle_game_engine_icon.png’: No such file or directory
Makefile:11: recipe for target 'html' failed
make: *** [html] Error 1
Thou, html folder is generated correctly. I couldn't find any cge-www like directory on in CGE installation. And I have no inkscape installed :) Maybe, just providing an alternative pre-rendered "castle_game_engine_icon.png" in "logo" folder would be good?
I've looked through the errors and fixed a few errors (see my latest commit), however I'm not sure about the "groupbegin/groupend" and "could not resolve link"... I've attached the full pasdoc log after "fixing".
A little more about documentation.
I found ISO/IEC 19775-1, Extensible 3D (X3D) to be a very useful document :)
However, in CGE some nodes, such as TBillboardNode, don't have any description at all.
As far as they state:
Unless otherwise specified, no part of this publication may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm, without permission in writing from either ISO at the address below or ISO's member body in the country of the requester.
- we can't copy the node description to the game engine documentation, only link to it, right? Well, even that would be much better than Class TBillboardNode... Description: no description available, TAbstractX3DGroupingNode description follows: no description available, TAbstractGroupingNode description follows.
What can be solutions?
1. Just make a link in the corresponding nodes description on Web3D Consortium website. (+) easy and quick (-) requires Internet access and "leads outside the engine documentation".
2. I couldn't find any license or copying info in my downloaded files, but as far as they provide a free download link it might be "available" for re-hosting. I.e. we can make a "local" copy of the standard specifications and link to the local folder. (+) easy and quick, no Internet required (-) link will lead outside of the engine documentation.
3. (BEST) Integrate the standard specifications text inside the nodes description. However, it is highly unlikely that license allows that.
4. Rewrite the specifications in a way that it won't loose any critical information but will not be a "derivative work" of the standard specifications. (Providing a link to official standard text of course). (+) best variant (-) a lot of work.
I think I already have the understanding enough to take that part of work for myself (as usually I'm fast to start but slow to finish :)). And it will be very useful for me myself, because I'll eventually take time to read the x3d standard specifications thoroughly. And I think I've already "caught" the commenting style and syntax - at least much better than my last attempt :)
However, I'm not sure which path to choose. What do you think about this?
1. Provide an active link for every node (even for those which have a description) to online x3d standard.
2. Write a description for the nodes which don't have one based on x3d standard (but not copying).
3. Extend description for the nodes which already have some description, but it doesn't cover all the standard specifications issues.
I've tried writing a description for TCollisionNode and TBillboardNode. Check if that's ok...
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
... which, as I realize now, is not really a good solution:) It makes spotting other warnings difficult.
So, I filtered them out in the script. The "make html" output is much cleaner now:)
Warning[1]: Could not resolve link "EConvertError" (from description of "CastleXMLConfig.TCastleConfig.GetBoolean")
That's also normal. PasDoc tries to link to exception names, but it cannot if it's an exception class in the standard Pascal library. This will be corrected one day in PasDoc (to simply not output these messages, at default verbosity; which should be a trvial patch to PasDoc but so far noone had time to do it:).
These warnings are also filtered out now.
Another error from PasDoc that you can temporarily ignore is that it cannot yet link to enumerated type values (that is, in "TXx = (xxOne, xxTwo)", you can link to "TXx" type, but you cannot link to "xxOne"). This is not filtered out for now.
I did some fixes, and the only pasdoc warnings you should see now are:
...
Info[2]: Now parsing file ./game/castlescenemanager.pas...
Info[2]: Now parsing file ../doc/pasdoc/introduction.pasdoc...
Info[2]: ... 179 Source File(s) parsed
Info[2]: Creating links ...
Info[2]: ... links created
Info[2]: Expanding descriptions (pass 1) ...
Info[2]: Expanding descriptions (pass 2) ...
Warning[1]: Could not resolve link "TBlendingSort.bs3D" (from description of "CastleBoxes.TBox3D.CompareBackToFront3D")
Warning[1]: Could not resolve link "TBlendingSort.bs3D" (from description of "CastleBoxes.TBox3D.CompareBackToFront2D")
Warning[1]: Could not resolve link "tiErrorBackground" (from description of "CastleControls.TCastleTheme.MessageErrorBackground")
Warning[1]: Could not resolve link "usEncloseReferenceSize" (from description of "CastleUIControls.TUIContainer.UIReferenceWidth")
Warning[1]: Could not resolve link "usFitReferenceSize" (from description of "CastleUIControls.TUIContainer.UIReferenceWidth")
Warning[1]: Could not resolve link "usExplicitScale" (from description of "CastleUIControls.TUIContainer.UIExplicitScale")
Info[2]: ... Descriptions expanded
Info[2]: Writing Docs for unit "Castle2DSceneManager"
Info[2]: Writing Docs for unit "Castle3D"
...
/castle_game_engine_icon.png’: No such file or directory
Makefile:11: recipe for target 'html' failed
The castle-engine/doc/pasdoc/Makefile expects that one of the following is true:
You have inkscape installed and available on $PATH.
Indeed, this was convoluted:) It changed it to use a ready png file from logo/ directory, if you don't have inkscape:)
However, in CGE some nodes, such as TBillboardNode, don't have any description at all.
Check the latest engine sources from GitHub:) Before announcing this on Facebook/Google+, I spend a day fillig out all the node description names.
Indeed, we cannot copy the descriptions literally, as far as I know. Writing a simple sentences on our own, with the same meaning, is OK. Note that this is an open standard, and these people want you to use their specification, and documentation like X3D tooltips http://www.web3d.org/x3d/content/X3dTooltips.html or http://doc.instantreality.org/documentation/nodetype/ are already sometimes quite close to the specification wording (but indeed, not literal copying). IOW: we cannot copy the descriptions literally, but we do not have to be paranoid and phrase things deliberately completely different than in the spec. They want us to spread the information:)
We could host a local copy of X3D specification, but that's a complication I would like to avoid, at least for now. But we can indeed link to the X3D specification pages. This is what pages like http://michalis.ii.uni.wroc.pl/cge-www-preview/x3d_implementation_grouping.php already do, and we can make these links from actual Pascal comments too.
Moreover, we can add our own description at everything. I don't think we can (or should) document everything precisely, in details --- we can refer people to the X3D specification for details. That's the purpose of X3D specification after all, to document all the details.
So, my idea is to:
Place a (short) description in the Pascal documentation. It should be useful, but it doesn't need to cover all the details.
And link to X3D specification online, for people interested in the details.
So, my idea is a mixture of your proposals:) Short description in our docs (that we have written on our own) + link to X3D specification.
I've tried writing a description for TCollisionNode and TBillboardNode. Check if that's ok...
Great! Thank you! I'll look into it shortly!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Update: the mk_dosc.sh output should contain no warnings now. If you use the latest PasDoc from GitHub https://github.com/pasdoc/pasdoc . As I just implemented the ability to link to an enum member in PasDoc:)
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
While trying to generate CGE documentation I get
./mk_docs.sh: line 137: pasdoc: command not foundeven if I copy pasdoc to this folder. I've downloaded Linux version of pasdoc, but it doesn't provide any means of installation - just a standalone application. There are 2 files pasdoc_gui and pasdoc in the bin folder and doc folder with license and other similar files. While pasdoc_gui works fine pasdoc says "cannot execute binary file". pasdoc_gui requires some .pds file as a preset, which isn't available for Castle Game Engine.Maybe console-version pasdoc it is 32 bit only?
pasdocs_gui works perfectly for me and I've successfully generated docs for my game :) But generating Castle Game Engine documentation requires much more settings which is not "just copy" to pasdocs_gui.
(Sorry for the delay in answering, I took a short vacation:) I'm back now, and will answer everything as I go through my backlog:)
The PasDoc release doesn't provide any means of installing it, we just let you unpack it anywhere and (optionally) make your environment variable $PATH contain the bin/ subdirectory. On Linux, you can e.g. add something like
export PATH="$PATH:$HOME/installed/pasdoc/bin"
to your .bashrc.
On Debian or Ubuntu or derivatives, you may also find a pasdoc package:)
In Castle Game Engine:
The script mk_docs.sh assumes that you have already set your $PATH as needed, and it simply runs "pasdoc", which means that the binary "pasdoc" is searched on $PATH (but not in the current directory, this is how Unix shells always behave, they do not implicitly search the current directory).
Indeed, we don't provide a .pds file for pasdoc_gui. It would duplicate the information from mk_docs.sh, and mk_docs.sh is a little more flexible.
So, the remaining problem is: why does (non-gui) pasdoc say "cannot execute binary file" on your system? For this, I don't know the answer yet... On https://sourceforge.net/projects/pasdoc/files/ , you can download either 64 or 32 version for Linux. If you get the correct one, it should work. What is weird: both pasdoc and pasdoc_gui are either compiled 64bit or 32bit (I double-checked it now), so they should either both fail or both work. You can test what is binary architecture by "file .../bin/pasdoc" in console, it should say "ELF 64-bit LSB executable" or "ELF 32-bit LSB executable", and it should of course match your system:)
I've downloaded pasdoc-0.14.0-linux-x86_64.tar.gz file, so it should be 64 bits. And both bin files appear to be 64 bits. Namely:
Works the same way under ROOT. The file is located at NTFS file system, but it doesn't work if copied to native EXT3 (i.e. Linux home folder) either.
P.S. Oddly, pasdoc_gui also tells the same thing "cannot execute" in console, however, it still works fine if I doubleclick-execute it from file manager (Thunar).
Strange... something seems to be wrong with my setup...
I've downloaded a debian package from repository, and I'll try it today evening.
The Unix shells do not automatically search for the specified program in the current directory. They only search the things on your $PATH environment variable.
So (if you have not yet set your $PATH environment variable to include "...pasdoc/bin") then doing
answers "command not found" because it cannot find "pasdoc" on $PATH.
To execute the binary in the current directory, you must provide the directory explicitly, e.g. by "./" prefix. This will work:
Google "unix execute command current directory" for more:) http://unix.stackexchange.com/questions/4430/why-do-we-use-to-execute-a-file , http://askubuntu.com/questions/320632/why-do-i-need-to-type-before-executing-a-program-in-the-current-directory :)
As for why "bash pasdoc" fails: using "bash xxx" is a way to execute bash scripts, not a binary program. It answers "cannot execute binary file", to tell you that the binary file was unexpected --- it expected a text file (shell script).
It's not about 32-bit vs 64-bit. "bash xxx" cannot execute any binary file.
Double-clicking on a program works, because Thunar executes it correctly (depends on the implementation, but most likely it doesn't use shell to execute the program at all).
Thunar actually executes both console and GUI programs, they both work, but when you run console "pasdoc' then nothing is shown (the output goes to a special file "/home/michalis/.xsession-errors"; unlike from Windows, on Linux you will not get a "blinking" terminal window if you execute a console command by double-clicking).
All this is related to how Unix and Unix shells work, you can reproduce this with any program on your system, compiled with FPC or not. This is
If you would install pasdoc from the Debian package, then it would be already available on $PATH (Debian package would place the pasdoc binary in /usr/bin). So running "pasdoc" would work. (But not because "pasdoc" binary was different! Only because it would be already installed on $PATH.)
Ooops... My bad as usually :) I was absolutely sure I always ran executables this way... But now I recall all of those had some sort of their own .sh script to start.
Thanks a lot and sorry for disturbing you.
Thanks a lot again! After installing a Debian package everything works. I'm using pasdoc_0.14.0-1_amd64.deb from the Debian repository which looks like the latest version.
I get a lot of similar warnings like:
Warning[1]: Tag "groupbegin" is not implemented yet, ignoring (in description of "CastleSceneCore.TCastleSceneCore.SetTime")
Warning[1]: Tag "groupend" is not implemented yet, ignoring (in description of "CastleSceneCore.TCastleSceneCore.IncreaseTimeTick")
and
Warning[1]: Could not resolve link "EConvertError" (from description of "CastleXMLConfig.TCastleConfig.GetBoolean")
and a final error
if which inkscape > /dev/null; then \ inkscape ../logo/castle_game_engine_icon.svg \ --export-width=256 \ --export-height=256 \ --export-background=white \ --export-background-opacity=255 \ --export-png=html/castle_game_engine_icon.png \ ; else cp /media/VST/CGE/castle-engine../cge-www/htdocs/images/castle_game_engine_icon.png html/; fi
cp: cannot stat ‘/media/VST/CGE/castle-engine../cge-www/htdocs/images/castle_game_engine_icon.png’: No such file or directory
Makefile:11: recipe for target 'html' failed
make: *** [html] Error 1
Thou, html folder is generated correctly. I couldn't find any cge-www like directory on in CGE installation. And I have no inkscape installed :) Maybe, just providing an alternative pre-rendered "castle_game_engine_icon.png" in "logo" folder would be good?
I've looked through the errors and fixed a few errors (see my latest commit), however I'm not sure about the "groupbegin/groupend" and "could not resolve link"... I've attached the full pasdoc log after "fixing".
Last edit: EugeneLoza 2017-01-23
A little more about documentation.
I found ISO/IEC 19775-1, Extensible 3D (X3D) to be a very useful document :)
However, in CGE some nodes, such as TBillboardNode, don't have any description at all.
As far as they state:
Unless otherwise specified, no part of this publication may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm, without permission in writing from either ISO at the address below or ISO's member body in the country of the requester.
- we can't copy the node description to the game engine documentation, only link to it, right? Well, even that would be much better than Class TBillboardNode... Description: no description available, TAbstractX3DGroupingNode description follows: no description available, TAbstractGroupingNode description follows.
What can be solutions?
1. Just make a link in the corresponding nodes description on Web3D Consortium website. (+) easy and quick (-) requires Internet access and "leads outside the engine documentation".
2. I couldn't find any license or copying info in my downloaded files, but as far as they provide a free download link it might be "available" for re-hosting. I.e. we can make a "local" copy of the standard specifications and link to the local folder. (+) easy and quick, no Internet required (-) link will lead outside of the engine documentation.
3. (BEST) Integrate the standard specifications text inside the nodes description. However, it is highly unlikely that license allows that.
4. Rewrite the specifications in a way that it won't loose any critical information but will not be a "derivative work" of the standard specifications. (Providing a link to official standard text of course). (+) best variant (-) a lot of work.
I think I already have the understanding enough to take that part of work for myself (as usually I'm fast to start but slow to finish :)). And it will be very useful for me myself, because I'll eventually take time to read the x3d standard specifications thoroughly. And I think I've already "caught" the commenting style and syntax - at least much better than my last attempt :)
However, I'm not sure which path to choose. What do you think about this?
1. Provide an active link for every node (even for those which have a description) to online x3d standard.
2. Write a description for the nodes which don't have one based on x3d standard (but not copying).
3. Extend description for the nodes which already have some description, but it doesn't cover all the standard specifications issues.
I've tried writing a description for TCollisionNode and TBillboardNode. Check if that's ok...
That's normal. I'm using a tag that is not implemented yet in PasDoc. See https://github.com/pasdoc/pasdoc/wiki/MichalisKamburelis#-support-for-groups-of-items . I plan to implement it one day in PasDoc, until then -- you have to simply ignore these warnings.
... which, as I realize now, is not really a good solution:) It makes spotting other warnings difficult.
So, I filtered them out in the script. The "make html" output is much cleaner now:)
That's also normal. PasDoc tries to link to exception names, but it cannot if it's an exception class in the standard Pascal library. This will be corrected one day in PasDoc (to simply not output these messages, at default verbosity; which should be a trvial patch to PasDoc but so far noone had time to do it:).
These warnings are also filtered out now.
Another error from PasDoc that you can temporarily ignore is that it cannot yet link to enumerated type values (that is, in "TXx = (xxOne, xxTwo)", you can link to "TXx" type, but you cannot link to "xxOne"). This is not filtered out for now.
I did some fixes, and the only pasdoc warnings you should see now are:
The castle-engine/doc/pasdoc/Makefile expects that one of the following is true:
You have inkscape installed and available on $PATH.
Or you have cge-www repository, https://github.com/castle-engine/cge-www , cloned, and placed as a sibling of a parent of directory $CASTLE_ENGINE_PATH.
Indeed, this was convoluted:) It changed it to use a ready png file from logo/ directory, if you don't have inkscape:)
Check the latest engine sources from GitHub:) Before announcing this on Facebook/Google+, I spend a day fillig out all the node description names.
Indeed, we cannot copy the descriptions literally, as far as I know. Writing a simple sentences on our own, with the same meaning, is OK. Note that this is an open standard, and these people want you to use their specification, and documentation like X3D tooltips http://www.web3d.org/x3d/content/X3dTooltips.html or http://doc.instantreality.org/documentation/nodetype/ are already sometimes quite close to the specification wording (but indeed, not literal copying). IOW: we cannot copy the descriptions literally, but we do not have to be paranoid and phrase things deliberately completely different than in the spec. They want us to spread the information:)
We could host a local copy of X3D specification, but that's a complication I would like to avoid, at least for now. But we can indeed link to the X3D specification pages. This is what pages like http://michalis.ii.uni.wroc.pl/cge-www-preview/x3d_implementation_grouping.php already do, and we can make these links from actual Pascal comments too.
Moreover, we can add our own description at everything. I don't think we can (or should) document everything precisely, in details --- we can refer people to the X3D specification for details. That's the purpose of X3D specification after all, to document all the details.
So, my idea is to:
So, my idea is a mixture of your proposals:) Short description in our docs (that we have written on our own) + link to X3D specification.
Great! Thank you! I'll look into it shortly!
Update: the mk_dosc.sh output should contain no warnings now. If you use the latest PasDoc from GitHub https://github.com/pasdoc/pasdoc . As I just implemented the ability to link to an enum member in PasDoc:)