How to add an example to the documentation of a procedure

[Ted Kosan]

Christopher and Kyle,

I am going to have each of you add one example to a ".mpws" file in the library that is tagged with a "*** MISSING EXAMPLES ***" message in the build output. Use the following procedure to do this:

1) Update to commit 599705b4 of MathPiperIDE using "git pull".

2) Build MathPiper inside of NetBeans.

3) Look in the build output, and select a ".mpws" file that is tagged with "*** MISSING EXAMPLES ***" which you think you can add an example to.

4) Set the "Project Configuration" to "Graphic Console". This can be done by selecting "Run -> Set Project Configuration -> Graphic Console" or by using the list that is immediately below the "Run" menu.

5) Run the "Graphic Console" using the green run/play button.

6) When the console is displayed, create an example use of the procedure you selected.

7) Open the file mathpiperide/src/library_apps/mathpiper4/src/org/mathpiper/scripts4/units/RecognizedUnitsAll.mpws. This file uses a method to place examples in the documentation that uses a "%mathpiper" fold and a tag named "*EXAMPLES" instead of an "*E.G." tag. The way it works is the build system looks for a "%mathpiper" fold that has its "subtype" attribute set to "in_prompts". The code to the left of the "->" symbol represents code that will be run, and the text to the right of this symbol is the result the code produces.

The build system will convert the contents of an "in_prompts" fold into examples where the "*EXAMPLES" tag is located. The advantage of this method of adding examples over the "*E.G." method is that the examples can be automatically tested.

8) In the ".mpws" file you selected, try to use the "*EXAMPLES" method instead of the "*E.G." method to add an example. If you have trouble doing this, let me know.

9) After you have added an example to the ".mpws" file, rebuild MathPiper, run the graphic console, select the "Docs" button that is on the right side of the console window, and verify the example was added to documentation correctly.

10) Submit your changes using a pull request.

Let me know if you encounter problems or have questions.

Ted

[Christopher McCormick]

Ted, 

I was going through the BitBucket tutorial and tried to create a branch, but it says I don't have permission to create a new branch. I wasn't sure if I needed to first get privileges from you or if I am going in the wrong direction. Thanks!

Christopher

--
You received this message because you are subscribed to the Google Groups "mathpiper-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mathpiper-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/mathpiper-dev/CAOJRwx0ntp%3Dfqi6Wo3q7sv67v6ehAn_AkaV0QTQE0tJWW0Cn-g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Ted Kosan]

Christopher,

Try using the forking workflow procedure that is described in the following webpages:

https://www.atlassian.com/git/tutorials/making-a-pull-request

https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow

Let me know if you encounter problems.

Ted

To view this discussion on the web visit https://groups.google.com/d/msgid/mathpiper-dev/CAEL8pk5Cttryq1mK2%3DtGWGtEeUywyU-t9sa1aTaB39eLZD56_g%40mail.gmail.com.

[Kyle Johnson]

I was having a little trouble as well but I think I may have figured it out. I just want to make sure I am going down the right path before I do anything too detrimental.

So I forked using this guide:

https://confluence.atlassian.com/bitbucket/forking-a-repository-221449527.html 

Which publishes a copy of the mathpiper repo under my own bitbucket account.

Next, I git cloned into a local/origin folder within my git repo folder (this will be the repo I will be programming in).

PS C:\Users\Brumo\desktop\git\origins> git clone https://Brumo...@bitbucket.org/Brumous101/mathpiperide.git

Then,  I did a git add remote upstream which links my local repo (origin) to the master branch.

PS C:\Users\Brumo\desktop\git\mathpiperide> git remote add upstream https://Brumo...@bitbucket.org/tkosan/mathpiperide.git

My question originally was how does the local and upstream know that they are connected so that when i finally do a pull request it will communicate with the master branch. Is it just because of the original step of forking the repo knows where I originally branched from? 

At this point do you think I am good to begin work on the examples (C:\Users\Brumo\desktop\git\origins>)?

I will need to copy the lib folders from the master copy of mathpiper to my origin copy as well right?

Also, is 599705b4 just the latest master branch of mathpiper? Is there a way to pull a legacy version of mathpiper if not?

Thanks!

Kyle

To view this discussion on the web visit https://groups.google.com/d/msgid/mathpiper-dev/CAOJRwx2CUsqRz_obrXMHdQX04%3DSVa7zrqQ3eqmdfZ9ohC%3DNBQA%40mail.gmail.com.

[Ted Kosan]

Kyle wrote:

> Is it just because of the original step of forking the repo knows where I originally branched from

This is my understanding of how the system knows where the fork came from.

> At this point do you think I am good to begin work on the examples (C:\Users\Brumo\desktop\git\origins>)?
>
> I will need to copy the lib folders from the master copy of mathpiper to my origin copy as well right?

Yes to both of these.

> Also, is 599705b4 just the latest master branch of mathpiper?

It was at the latest commit at the time I sent the email. If you run
the command "git log", you will see a list of the most recent commits.

> Is there a way to pull a legacy version of mathpiper if not?

The following blog post discusses techniques for accomplishing this
(just ignore the information that is specific to GitHub):

https://coderwall.com/p/xyuoza/git-cloning-specific-commits

Ted

[Kyle Johnson]

I was attempting to run the graphic console in net beans and this runs in the console until i manually make it stop.

I have tried deleting my origin and cloning from my fork a few times and I keep getting this error.

Any ideas?

[Ted Kosan]

Kyle,

When you build MathPiper inside of NetBeans, does it build without any errors?

Ted

> --
> You received this message because you are subscribed to the Google Groups "mathpiper-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to mathpiper-de...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/mathpiper-dev/e5ea4ab5-0389-4839-9576-b7217af374be%40googlegroups.com.

[Kyle Johnson]

Yeah it gives me this:

> To unsubscribe from this group and stop receiving emails from it, send an email to mathpi...@googlegroups.com.

[Ted Kosan]

Kyle,

In this screenshot I don't see the "build" and "compile_quick" buttons
that we added to the toolbar the last time we met. How are you
building MathPiper without using the "build" button?

Ted

> To unsubscribe from this group and stop receiving emails from it, send an email to mathpiper-de...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/mathpiper-dev/0b5a46d9-fadb-4f69-8eb4-54e14b952378%40googlegroups.com.

[Kyle Johnson]

My bad, I got it fixed. I was using the build.xml from the master mathpiper4 button. It disappeared after I closed the master project and it wasn't building the origin when I used that button. It works after i readded it to this origin project! 

[Kyle Johnson]

So I inserted my example into the file but when I try to build it just gives me this error. (It goes off screen and says the issue is C:\Users\Brumo\Desktop\git\origins\mathpiperide\src\library_apps\mathpiper4\build\org\mathpiper\builtin\procedures\plugins\jfreechart\plugins_list.txt). I haven't made any changes to that file or anything either. I have also tried Compiling and then building as well but get the same error.

[Christopher McCormick]

Ted,

When changing from *E.G. to *EXAMPLES, is there a way to include comments on the examples? Any plain text included in the in_prompts fold seems to cause the build to fail, unless it is formatted input -> result.

Christopher

[Ted Kosan]

Christopher,

The *EXAMPLES system does not currently support comments. If you would
like to enhance it to support comments, create an issue on Bitbucket
for this enhancement, assign yourself as the Assignee, and I will
provide information in the issue on how to proceed.

Ted

> --
> You received this message because you are subscribed to the Google Groups "mathpiper-dev" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to mathpiper-de...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/mathpiper-dev/597b6dc1-ddf5-4f41-99b7-4605f710d28d%40googlegroups.com.

[Christopher McCormick]

Ted,

I'd be happy to work on it. I created the issue on Bitbucket but was unable to assign myself. 

Christopher

[Christopher McCormick]

Ted,

When working on automatic tests for procedures with side effects, is there a way to access the side effects for testing purposes?

Christopher

[Ted Kosan]

Christopher,

"PipeToString" can be used for this purpose:

Verify(PipeToString() DumpErrors(), "Error: testing
Error: testing1234: [1, 2, 3, 4]
");

Ted

> --
> You received this message because you are subscribed to the Google Groups "mathpiper-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to mathpiper-de...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/mathpiper-dev/f91963be-a7da-4d2e-ae83-a3b875f14ca0%40googlegroups.com.

[Christopher McCormick]

Ted,

Okay great. Now for a procedure like UnparseMath2D that returns True and the actual desired information is output in the Side Effects, is there a way to access those side effects using PipeToString? Or can DumpErrors be used for that purpose?

[Ted Kosan]

Christopher,

PipeToString will capture side effects from any procedure, including UnparseMath2D. So in the example, replace DumpError with UnparseMath2D.

Ted

On Fri, Jun 21, 2019, 8:50 AM Christopher McCormick <cjmcco...@gmail.com> wrote:

Ted,

Okay great. Now for a procedure like UnparseMath2D that returns True and the actual desired information is output in the Side Effects, is there a way to access those side effects using PipeToString? Or can DumpErrors be used for that purpose?

--

You received this message because you are subscribed to the Google Groups "mathpiper-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mathpiper-de...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/mathpiper-dev/cb3910e6-cbb0-45a6-b2e9-4ccb2e2fa0be%40googlegroups.com.