Alpha Video Training
Results 1 to 11 of 11

Thread: Documentation?

  1. #1
    Bo Vandenberg
    Guest

    Default Documentation?

    Looking at the various uploaded databases it occurs to me that there is not a generally held place to put documentation. I'm thinking mostly of the 'notes to self' sort of designer notes that are sometimes tucked into source code.

    While it is of course possible to include a readme.txt file I don't often look at the component files of the directory. I suppose you could have a Report or Form with designer notes -- but I'd really like something that showed up under the Code Tab. That way it wouldn't be visible to the runtime.

    Is there a script or code format that can never be executed, that the db would always ignore? Something people might use to leave notes to themselves or fellow maintainers?

    Bo

  2. #2
    "Certified" Alphaholic
    Real Name
    Tom Cone Jr
    Join Date
    Apr 2000
    Location
    Florida
    Posts
    23,307

    Default RE: Documentation?

    Bo, this is a good question. My practice is to keep a journal using my favorite word processor, storing it in the database folder during development.

    I suppose it wouldn't be too hard to create another table and use it to track changes and development ideas. If memory serves Barry Rochford has published an article explaining how he does it. You might check the articles index at www.learnalpha.com.

    -- tom

  3. #3
    "Certified" Alphaholic
    Real Name
    Tom Cone Jr
    Join Date
    Apr 2000
    Location
    Florida
    Posts
    23,307

    Default RE: Documentation?

    Bo,

    By the way, I'm curious about why you think items on the Code page are less visible to the runtime than layouts listed on the Form or Report pages ? Since the runtime can't get to the control panel aren't they all equally invisible ?

    -- tom

  4. #4
    "Certified" Alphaholic Scott Emerick's Avatar
    Real Name
    Scott Emerick
    Join Date
    Dec 2000
    Location
    Central Virginia/ North Carolina Border
    Posts
    2,154

    Default RE: Documentation?

    Bo,

    Tom has the best thoughts about using a table to store your "memos" in. The downside would be that the table would show in the control panel of a runtim IF you allow the user to see/ access the CP.

    If you just want to keep notes in the code tab as a script you could create a script, make the first line END and then use comments to keep your notes.

    Personally, I would take Tom's advise of using the table and then just password protect it IF the user has access to the CP. This will allow you to use all the formatting and search features of A5 to make your life easier.

    Scott

  5. #5
    Member
    Real Name
    Edward Schulz
    Join Date
    Jul 2000
    Posts
    742

    Default RE: Documentation?

    Hi Guys,

    Using Tom's approach seems to be the best. I'd like to add that possibly placing that table outside of the DB folder and having a hidden button on the main menu to display or print it. I just don't know if it would show then in the CP.

    Might work?
    efs

  6. #6
    Former Alpha Employee JerryBrightbill's Avatar
    Real Name
    Jerry Brightbill
    Join Date
    Apr 2000
    Posts
    5,171

    Default RE: Documentation?

    Bo

    In addition to the ideas already mentioned, you can leave comments directly in the code. To commnet a line out in xbasic, just place single quote (') at the start of a line and the program ignored that line. I like to leave some comments in the code for my own information to explain what the code is doing. For example, here would be a typical comment section in an xbasic script

    '--------- Start Process ----------
    'These would be comment lines explaining what happens next
    ' This could be something like:
    ' Calculates balance by subtracting payments from balance
    ' Places result in customer file
    '--------- End Comments ------------

    I have found this a good way to place simple notes. If more extensive information is needed, I create a work processor file that has notes on what I am doing.

    Jerry

  7. #7
    Bo Vandenberg
    Guest

    Default RE: Documentation?

    Tom

    In the runtime happenstance might give users access to the Control Panel but the code window is automatically hidden. Right click inside of the runtime control panel and try to enable the code window -- it isn't there.

    Like you Tom, I also keep a second editor running with snippits of code, words o wisdom, project notes etc... (I think I mentioned this before.) I like the code window because its both the most flexible and the most simple. Copy to or from my editor .

    Could you have a standard readme header that would open a web page or send an email if the script was run? Then one could explain the application with the rest of the script.

    I'm thinking mostly for adding helpfiles to example applications. I'd like to comment a DB from the Phorum with the message text that describes it in a script called U_Readme_A5.

    Unfortunately even after an 'end' the imported text needs to be commented or it appears as an error and the editor won't close. I'd like to make Alpha completly ignore the import in some sort of remark block.

    I dont think that pure text files would ever be very big. I don't know if their size or management would become an issue.

    I hope you will forgive me if I illustrate with one of your own files (and your own words :) ).

  8. #8
    Member
    Real Name
    Paul French
    Join Date
    Apr 2000
    Location
    Iowa
    Posts
    702

    Default RE: Documentation?

    How about keeping it in a table, but dropping the table from the database before distribution. Leave the table in the database folder so it's there, but it wouldn't be visible to the end user even if they have access to the control panel. You could even add a bit of password protected code that would add the table back to the database so it would become available if needed, and a way to drop it again when you were done.

  9. #9
    Member
    Real Name
    Paul French
    Join Date
    Apr 2000
    Location
    Iowa
    Posts
    702

    Default RE: Documentation?

    Isn't he really just asking for implementation of remark blocks in the editor so you could mark the beginning of imported text and the end of imported text without adding a remark symbol to each line -- or as an alternative, highlight all of the imported lines and let the editor insert remark symbols as some editors do?

  10. #10
    Bo Vandenberg
    Guest

    Default RE: Documentation?

    Thanks Paul

    I guess that is what I'm asking for (The former -- mark beginning and end). But I also wonder if others would use this system and if anyone can, constructively, kick holes in it for me.

    Bo

  11. #11
    Alpha Software Employee Lenny Forziati's Avatar
    Real Name
    Lenny Forziati
    Join Date
    Nov 2001
    Location
    Alpha Software
    Posts
    4,682

    Default RE: Documentation?

    highlight all of the imported lines and let the editor insert remark symbols as some editors do?

    This capability is already there. Highlight your block of text and hit CTRL+' or click the toolbar icon (see attached image). You can also uncomment a block with the next icon on the toolbar (also in image) or with CTRL+;

    -Lenny

Similar Threads

  1. New PDF Documentation
    By Edward Larrabee in forum Alpha Five Version 5
    Replies: 0
    Last Post: 10-21-2004, 06:34 AM
  2. New PDF Documentation
    By Edward Larrabee in forum Announcements
    Replies: 0
    Last Post: 10-21-2004, 06:33 AM
  3. Documentation
    By Peter.Greulich in forum Alpha Five Version 5
    Replies: 5
    Last Post: 07-23-2002, 04:39 AM
  4. A5 Documentation
    By Allen Palmer in forum Announcements
    Replies: 2
    Last Post: 03-27-2002, 06:56 PM
  5. Documentation
    By James Peterson in forum Alpha Five Version 1
    Replies: 2
    Last Post: 08-02-2001, 01:10 AM

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •