ksp-kos / kos_doc Goto Github PK

KSP has a 6 hour day :P

The following problems exist:

1 - The example for LIST SENSORS shows code that fails if you run it, because it tries using a reserved keyword "SENSORS" as a variable name. FIX: Change "FOR SENSOR IN SENSORLIST" to "FOR S IN SENSORLIST".

2 - The Page for SHIP:SENSORS:GRAV claims that it returns a number rather than a vector. It actually returns a Vector.

Document the config suffixed structure and the config file.

I added some new ".md" files to the documentation and made a few edits to existing ones, but I don't know how to tell the system to regenerate the documentation from the source files, and therefore I'm not certain whether or not the links I made to them are right (I can't test following the links yet because the pages they point to give 404 Not Found errors since the docs haven't been regenerated yet.).

Is there any reason that page isn't accessible ?
The link is missing in the addons list and on the addons page.

The bottom of all the pages still says:
"erendrake maintains kOS"
leftover from the days before merging with marianoapp's kRISC. It might be a good idea to include marianoapp in the footer.

The File i/o page claims that RUN just takes one argument - the filename - it fails to mention how to pass arguments.

The Variable page does mention DECLARE PARAMETER but the example of how to use it is wrong and needs fixing.

The use of the NEXTNODE special variable should be documented on the NODE page.

The reddit link on the top of the page doesnt go to the kOS subreddit

Currently the Ship Steering instructions don't mention that SAS overrides kOS's attempts to steer the ship.

for the next full release -I need to have a page about vecdraw.

As per issue #128 in the main code, document the fact that things like the clock and the state of consumables and positions and velocities and so on of the game are frozen in time during an update tick, and therefore you probably want a wait 0.0001 in most loops.

source/command/variable describes the notion of a "context level". Having read some of the code I recognize that this means "current subprogram or when/then", but there's no way a user of kOS is going to know what that means. Even if they're a programmer who knows a bit about OS terminology who knows what a "context record" means they still won't know how that concept maps to a kOS context.

In general, I think the documentation needs a way to explain to people how the scoping works:

If you create a variable in one place, what other places can you access it?

Does the 'declare' statement only work with SET variables, or will it let you define the scope of a LOCK variable as well?

If you are in a sub-program and create a variable implicitly using 'set' or 'lock' without a 'declare' statement, will the main program be able to see it or is its context purely local?

If you try to access a variable name but it doesn't exist in the current context, does it look for it in a more global context?

I'd be willing to write the documentation for it, but I'm not sure I'm qualified to, as I don't actually know all the answers to these questions myself, and have always been a bit confused by the behavior of this.

This looks like something that @marianoapp would know the most about.

As I was editing the List documentation to add the new [] syntax, I noticed that LIST is documented in two entirely different locations in the documentation:

source/structure/list.md

and

source/command/list.md

I only edited the version in source/structure/list.md, and didn't repeat the same information in source/comand/list.md because I'm wondering if this redundancy should be removed instead, as it makes documentation maintenance messy.

If I was doing this on a filesystem that supported symbolic links, I'd make source/command/list.md be a pseudonym that just points to source/structure/list.md so you can get to the same page through two different paths. I doubt I can do that with a git archive, though. Perhaps one can be made into just a stub of a page containing nothing more than a hyperlink to the other page.

Things in need of documenting:

(Released items can be documented now.
Pre-released features should be held off until they become fully released.)

For proper completeness I wanted to put the ELSE syntax into the documentation to coincide with whenever the release of that happens, but I didn't want the documentation to claim the ELSE syntax was already implemented, prior to that release going out.

Is there a good way to do that? i.e. is there such a thing as the 'development' fork of the documentation?

Everywhere there's a link like this:

    [visible text](link text) 

In the markdown script, if the link text is an absolute path from root (starts with "/KOS_DOC/") then it means I can't click through the links on my own locally generated copy because the file structure of the generated text changes the name of that root dir. To make it easier to test the docs first before putting them on the public site, I need to change all the links to be relative (i.e. "../structure/vector/" as opposed to "/KOS_DOC/structure/vector/"). That way they will work identically whether on the local copy or hosted publicly on the github file server.

Documentation is no longer in a separate fork, and we've gotten the docs into the main branch of https://github.com/KSP-KOS/KOS as just a subdirectory of the branch under the folder doc/

This is stale information to be ignored.

To add a document issue or pull request, please go here instead:
https://github.com/KSP-KOS/KOS_DOC_DEV
This repository you're looking at now is the static location that the published documents end up in after they've been edited. Most of the time, edits are not made in this fork. It is simply cloned directly from the development fork.

TO-DO: get this information into the documentation:

http://www.reddit.com/r/Kos/comments/250zmc/some_useful_new_info_regarding_antennas/