jalv2 & jallib - an introdcution

[Joep Suijs]

Hi all,

We discussed the need of introduction documentation for jallib/jalv2
on the jallib list. Toon and I made quite some progress on this
subject and since there are similar initiatives on the jalweb list, I
decided to release an early version of the result for review. Please
tell us what you think of this.

And as for all these initiatives: I think we should have a plan first
on what we need, how we get this and how we mainitain it. Creating
something is easy. Creating something usefull for a broader audiance
is a difficult, since it has to have a suitable form, needs to be
correct and complete (and it would be good to have an introduction and
advanced documentation / reference for the next level). The real hard
thing is to maintain what is created. And this is also the most
important one, otherwise there will be an other dead resource on the
subject, making it more difficult to achieve a decent result in the
future.

IMHO, the document enclosed could wel become the introduction guide.
It covers most of the subjects, except the language introduction,
hardware and programming (ICSP, bootloader that is).
The exended guide could be based the pjal documentation (which seems
to be ignored, except by sunish) and info from the api documentation
as a reference. The result will be documents, not a flashy site or
colorfull blog. Is that what we want to invest in? If so, we need a
few people contributing and someone who takes the rol of chief
editor...

Joep

[Wayne Topa]

Joep

I have not finished reading the whole document yet but as of now I
think You and Richard an on the right track. I like the style of the
writing and it is very readable.

I scanned the whole doc and see only one section I do not understand.
The PWM section is "over my head" but that might be because I am not
able to read Dutch! ;-)

Great job! I have s few suggestions on grammer but overall it looks
very helpful. THANKS!!

Wayne

[mattschinkel]

Great job guys, It's good to see this much needed documentation!

One suggestion for page 1

>Bert van Dam’s Starterpack. Bert created this starterpack to support his book “PIC Microcontrollers, 50 projects for beginners and experts”. Within this document, we will refer to this library set as ‘Starterpack’.

You should mention that berts lib files are free but the documentation
& examples are not.

>Jallib. Jallib is a team effort to create a clear, consistent set of libraries for JAL. It provides much functionality and supports over 300 different PIC microcontrollers
You should mention that the libs are free as well as the documentation
& examples, and that it is open source.

After all, this is the major difference between the two.

Also, since you said "we will refer to this library set as
‘Starterpack' ", you could also say "we will refer to this library set
as ‘JalLib-Pack’ ". Also maybe "Starterpack" should say "Bert's
Starterpack".

Matt.

>  jal_v2_and_jallib_introduction.pdf
> 657KViewDownload

[Sunish Issac]

Personally, I feel the migration document (from berts Starter Pack) should be independent of the Introductory manual of jalv2 and jallib. If that is the case, there needs no mention of Bert's starter pack in the Introduction Guide. Also Wouter's Start With Pics and mikroPascal help files can be used as good reference material in creating the docs.

I also would suggest to have circuit diagrams when examples are described.


In page 6 of the manual there's a small mistake, "So you we use ‘led’, we could have used" does not make sense.

The writing style and overall looks are pretty impressive. But IMHO the language reference guide should come out first, things like _usec_delay could easily be referenced then.

Sunish

[Sebastien Lelong]

Hi guys,

Here are some comments I can have reading this doc:

  - license: maybe a Creative Common license would better fit. CC is for content, while GPL is for code. Reading GPL, most articles won't apply to this documentation. More, Google Code two ways for licensing a project: 1 for the code (GPL, BSD, ...), 1 for the content (CC). There are different options in CC, wherever you want to allow commercial or not for instance. See: http://creativecommons.org/choose/

  - I agree with Sunish about migration beeing independent from jalv2/jallib introduction. I would even say this doesn't sound like a conversion/migration guide, it is, as the title says, an introduction. The part about Bertlibs (in Introduction) could also be named "Why jallib ?".

  - generally speaking, and taking ADC as an example, I don't think it's enough to get started with this information. As far as I'm concerned, I do need some detailed instructions. What is ADC ? It may be out of scope, still few words explaining what it does, an application example would help the novice to understand what this is about. Your mail about having to set ADC_NCHANNEL vs. not set_analog_pin() available and the part in my blog post could definitively be put here. Few words about theory, a global overview about it's handled in jalilb, then practice. I think when introducing a subject like a peripheral, there should be detailed instructions, hardware setup, photos, just to show how it looks like. Take user by the hand. This is what "Step by step" posts are about. We should discuss about integrate them directly into the document. This is my next bullet.

  - We probably need a way to centralize all the documentation, to avoid duplication and maintenance nightmare that comes with it. I don't know what is the original format for this document, but we'd need a text base format, not Word for instance. If we need to compile different sources of information, we need a way to do this easily. And it should be under SVN. With a text mode doc, you can also diff versions (and it's not a p.i.t.a switch on word to fix one typo...).

  - There are other posts from jalliblog you can use:
     - series about i2c: http://jallib.blogspot.com/2009/01/step-by-step-building-i2c-slave-with.html, http://jallib.blogspot.com/2009/01/step-by-step-building-i2c-slave-with_17.html and http://jallib.blogspot.com/2009/01/step-by-step-building-i2c-slave-with_20.html
     - PWM (for the upcoming section, hope not in Deutch...), showing two main applications: http://jallib.blogspot.com/2009/02/step-by-step-having-fun-with-pwm-and.html and http://jallib.blogspot.com/2009/02/step-by-step-having-fun-with-pwm-and_14.html


It's great to see this happen. As you suggest, we need to decide where we want to go with this, how much details, what should be included, what shouldn't, and most importantly be careful about duplication, particularly when it's about documentation duplication.

Cheers,
Seb
--
Sébastien Lelong
http://www.sirloon.net
http://sirbot.org

2009/8/16 Joep Suijs <jsu...@gmail.com>

[Joep Suijs]

Hi Guys,

Thanks for the feedback.

@Wayne: although it might be a bit difficult to learn, it is worth
while: Dutch is a very efficient language as you can see: in only a
few words everyting you need to know about PWM ;) ;)

@license - I go along with any license. The only thing which feels
unfair if it would be converted into a commercial product or it would
be extended and these extensions are not free to be used.

@tools. As announced, this document is written in word, since this
alows me to focus on the product, not on the tool. It is under svn
(but not jallib), but the bad thing is that subversion can't merge
versions. But I don't think the tool is a major issue here. Word does
pretty much what I need and the output is pdf. And if at a given time,
someone else wants to do a major upgrade, the text could be imported
in any tool, leaving only the markup to be redone. This is much less
effort then use a less-productive tool now.

And in general, I agree that although we started of as a migration
guide, it becomes more like an introduction. And there are still bits
to be aligned to this.
But the main issue is both explicit as implicit in all the messages.
My first goal was to make a small converion guide and this could well
be a small introduction guide. But small also means that there is a
lot not in there. Of course we could some hardware. And I agree that
it would be usefull to make a brief introduction on adc before go into
the details. And this still could be within a 'small' introduction
guide.
But as soon as it's there, there will be a need for more details on
<any subject>. And we could go this way and at some given point, we
will notice we wrote an extensive manual but also need a quickstart
guide (or small introduction guide).

Or to put it an other way: we go around in circles. There are realy
nice tutiorials of different topics on the blog. They are very usefull
if you are a bit up to speed with Jal and want to work on the topic at
hand. The complaint however was that people don't know how to start
(or to switch, when using Bert's starterpack). So one document with a
brief section the common topics in a logicas sequence could to the
job. And now we are at the point of expanding it to the depth of the
blog tutorials. We could, but then we are going to write a book ;)

What I like of the blog articles is that they are hands-on, complete
(hardware and software) and with nice pictures. This can only be
created and extended if they are independent of each other (since
dependency will become too complex to manage at some point). And this
independency is what makes it unsuitable for an introduction course.

You could of course adapt some articles and put them in some order on
the web (webbook?) This would then be a subset of the blog and some
(existing and new) articles won't fit in the structure.

We could also create a document as an 'umbrella', briefly covering all
topics and refer to other sources for more details. That's what I
tried with this document and we're about to discover if this could
work.

I'd be happy to extend this document a bit (especially if you can
contribute by sending me chapters ;). And for support, it might be a
good idea to create a few blog articles (like 'install jalllib +
jaledit & compile your first program', 'using an ICSP', 'using a
bootloader' and 'setup of a tutorial test system'). And ultimately, we
could have a detailled and in-depth blog on each subject in the guide.

Joep

PS I forsee that I won't have much time for this topic in the next
week, so no relpy does not mean I'm not interested ;)

[Eur van Andel]

On 16 Aug 2009, at 13:00 , Joep Suijs wrote:

We discussed the need of introduction documentation for jallib/jalv2

on the jallib list. Toon and I made quite some progress on this

subject and since there are similar initiatives on the jalweb list, I

decided to release an early version of the result for review. Please

tell us what you think of this.

It is excellent. It is aimed just above pure beginner level, which is good. 

IMHO, the document enclosed could wel become the introduction guide.

It already is.

It covers most of the subjects, except the language introduction,

hardware and programming (ICSP, bootloader that is).

The exended guide could be based the pjal documentation (which seems

to be ignored, except by sunish) and info from the api documentation

as a reference. The result will be documents, not a flashy site or

colorfull blog. Is that what we want to invest in? If so, we need a

few people contributing and someone who takes the rol of chief

editor...

It should not be longer than this. Reactions and questions should provide feedback fro improvement

<jal_v2_and_jallib_introduction.pdf>

On of these days, I will rewrite the jallist FAQ, since 90% of the original (0.4.60!) text remains. I'd love to include this document. 

---

ir EE van Andel e...@fiwihex.nl  http://www.fiwihex.nl

Fiwihex B.V. Wierdensestraat 74, NL7604BK Almelo, Netherlands

tel+31-546-491106 fax+31-546-491107

[mattschinkel]

Hey there,

We are currently working on new documentation, the PDF can be found on
SVN at doc\dita\tutorials\tutorials.pdf

This documentation will be in this PDF format as well as on the
website we are currently building www.justanotherlanguage.org.
Hopefully it will contain everything from beginner to the intermediate
level.

I see you uploaded a nice motor lib. (although I don't know much about
what it does). If you wish to create a tutorial, it would be much
appreciated and could be added to our documentation. Hopefully we will
someday have a tutorial for everything.

> On of these days, I will rewrite the jallist FAQ, since 90% of the
> original (0.4.60!) text remains. I'd love to include this document.

You are welcome to join us and contribute to our documentation, an FAQ
will be a part of it. We also hope to rebuild the jallist FAQ. We need
good contributers such as yourself!

Matt.

[funlw65]

Hi,

Is possible there few words about "for cycle" and examples of using
it? Also from what index start an array, 0 or 1 (the same for "for
cycle")? And examples on using it inside "for cycle" because are
related? I used JAL 0.4x and there was no "for cycle" and arrays...

Vasi

[mattschinkel]

I believe they both start at a zero value, this way there are 256
possibilities for for, and up to 256 array indexes. 0 to 255.

I think it will be a good idea for us to have a language FAQ in the
documentation, or a updated language reference chapter in the doc.

Seb, what do you think? Would kyle allow the language reference to be
ported to DITA so it can go on his website as well as
justanotherlanguage.org and the PDF?

Matt.

> > > tel+31-546-491106 fax+31-546-491107- Hide quoted text -
>
> - Show quoted text -

[Sebastien Lelong]

Seb, what do you think? Would kyle allow the language reference to be
ported to DITA so it can go on his website as well as
justanotherlanguage.org and the PDF?

I'm not sure he'll change this and use DITA but that's something to ask to him :)

Cheers,
Seb

[funlw65]

I think this is what is missing right now and is essential. Kyle's
short language description is not intuitive and in some parts is
confusing. Short examples are missing.

On Nov 22, 4:16 am, mattschinkel <mattschin...@hotmail.com> wrote:
> ..................

> I think it will be a good idea for us to have a language FAQ in the
> documentation, or a updated language reference chapter in the doc.
>
> Seb, what do you think? Would kyle allow the language reference to be
> ported to DITA so it can go on his website as well as
> justanotherlanguage.org and the PDF?

> .........................
> Matt.

Vasi

[mattschinkel]

Mostly I see new users having trouble "getting a bit out of a byte",
or making a simple button, etc. These are great things to have in a
language ref that are not clear in kyle's. Kyle's ref also still says
"var volitile", I'm sure he would love to have someone else take care
of it so he can work on other issues.

I would suggest someone who knows kyle better then myself ask him. Or
we can make our own new language ref?? A new language ref could
automatically be uploaded to kyle's website if he allows.

We can make a lang ref that can be a book of it's own, as well as
copied to a lang ref chapter in the documentation. The documentation
should contain everything needed to use jalv2/jallib.

Matt

[Joep Suijs]

Hi,

 

> Kyle's ref also still says "var volitile"

 

I probably missed something, but what's wrong with this?

 

> Or we can make our own new language ref?? A new language ref could

> automatically be uploaded to kyle's website if he allows.

A man with two clocks does not know the time... I don't think it is a good idea to have two (similar) language reference. And if I was maintaining a compiler, I'd keep control of the prime specification (i.c. the reference page) to myself...

However, an extensive reference, with examples and tricks is an other story!

 

Joep

[mattschinkel]

> > Kyle's ref also still says "var volitile"
>
> I probably missed something, but what's wrong with this?

nothing is wrong with that, but I would like to see updated stuff such
as ALIAS, examples, some other stuff that is not in the current ref,
as we are discussing. I suppose ALIAS is only a jallib prefrence over
var volitile.

> > Or we can make our own new language ref?? A new language ref could
> > automatically be uploaded to kyle's website if he allows.
>
> A man with two clocks does not know the time... I don't think it is a good
> idea to have two (similar) language reference. And if I was maintaining a
> compiler, I'd keep control of the prime specification (i.c. the reference
> page) to myself...
> However, an extensive reference, with examples and tricks is an other story!

I don't mean a copy of the current language ref, I do mean a new
"extensive one", or a "updated language ref that is extensive"

What is the right way to go about building this extensive ref? through
kyle, or on our own?

Matt.

[Rob Hamerling]

Hi Matt,

mattschinkel wrote:
> I suppose ALIAS is only a jallib prefrence over var volitile.

Hmmm, sound to me as if you think one is an 100% alternative for the
other? That is not the case. I'm afraid you haven't fully understood the
meaning of 'volatile'. The device files have many occurences of var
volatile, where alias is totally inappropriate! Chapter 7 of the JalV2
manual describes the purpose of volatile.

[Joep]

> However, an extensive reference, with examples and tricks is an other story!

Programming may look like (black) magic for many people, but it is an
ordinary craft. I would prefer the word 'techniques' in stead of
'tricks' when describing perfectly normal/legal ways to perform
operations in a certain programming language.

> What is the right way to go about building this extensive ref? through
> kyle, or on our own?

You have probably in mind a "JalV2 Programmer's Guide", which is
something else than a "JalV2 Language Reference Manual". The latter
describes the rules, the first describes how to apply rules (write a
program that obeys the rules).
And I think a Programmer's Guide should preferrably written by another
author! But of course it can be in co-operation.

Regards, Rob.


--
Rob Hamerling, Vianen, NL (http://www.robh.nl/)

[mattschinkel]

My suggestion I guess is that we have many small books (jallib
tutorials, extended jal ref, jaluino tutorials, etc). Also however, we
should compile them all into one "Big book of jal". Does this sound
good?

Seb, can you create a blank extended reference book on SVN so it can
slowly be created. maybe copy the other book and change the name to
something like "JAL+jallib Extended Code Reference", I am assuming we
may have some small jallib examples within this reference??

Matt.

[Sebastien Lelong]

Hi Matt,

Having multiple books doesn't seem like a bad idea to me, provided it's consistent. Separating practice (tutorials) and theory (intro, ref) allows readers to focus on what they need.

That said, I can obviously create a "big book". In theory, I could even pick some pages from Jaluino (external URLs) if needed. In practice, this feature seems not implemented in current DITA-OT.

So, it's possible. Question now is: what would be the Table Of Content ?


Cheers,
Seb

2009/11/24 mattschinkel <mattsc...@hotmail.com>

--

You received this message because you are subscribed to the Google Groups "jallib" group.
To post to this group, send email to jal...@googlegroups.com.
To unsubscribe from this group, send email to jallib+un...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/jallib?hl=en.

[Sunish Issac]

There should be a Language and Compiler Reference Manual along with a Programming manual with JALLIB. Just my personal opinion.

For those on the look out for creating new libraries, here's tteh TOC of the libraries mikroPascal.Now we have many alternatives in jallib, but many more could be added without much difficulty.

• ADC Library -
  
• CAN Library
• CANSPI Library
• Compact Flash Library
• EEPROM Library
• SPI Ethernet Library
• Flash Memory Library
• Graphic LCD Library
• T6963C Graphic LCD Library
• I²C Library
• Keypad Library
• LCD Library
• LCD8 Library
• Manchester Code Library
• Multi Media Card Library
• OneWire Library
• PS/2 Library
• PWM Library
• RS-485 Library
• Software I²C Library
• Software SPI Library
• Software UART Library
• Sound Library
• SPI Library
• USART Library
• USB HID Library
• Util Library
• Port Expander Library
• SPI GLCD Library
• SPI LCD Library
• SPI LCD8 Library
• SPI T6963C Graphic LCD Library

• Conversions Library
• Delays Library
• Math Library
• String Library

Sunish

[Sunish Issac]

Here's how mikroPascal Language Reference is organized,we can adapt and adopt

Lexical Elements

Whitespace
Comments
Tokens

Literals
Keywords
Identifiers
Punctuators

Program Organization

Program Organization
Scope and Visibility
Units

Variables
Constants
Labels
Functions and Procedures

Functions
Procedures

Types

Simple Types
Arrays
Strings
Pointers
Records
Types Conversions

Implicit Conversion
Explicit Conversion

Operators

Introduction to Operators
Operators Precedence and Associativity
Arithmetic Operators
Relational Operators
Bitwise Operators

Expressions

Expressions

Statements

Introduction to Statements
Assignment Statements
Compound Statements (Blocks)
Conditional Statements

If Statement
Case Statement

Iteration Statements (Loops)

For Statement
While Statement
Repeat Statement

Jump Statements

Break and Continue Statements
Exit Statement
Goto Statement

asm Statement

Directives

Compiler Directives
Linker Directives

Sunish

[funlw65]

Swordfish Basic come with library sources even in free version (except
SD and USB which is available only commercial versions).

Vasi

On Nov 24, 2:29 pm, Sunish Issac <sunish....@gmail.com> wrote:
> There should be a Language and Compiler Reference Manual along with a
> Programming manual with JALLIB. Just my personal opinion.
>
> For those on the look out for creating new libraries, here's tteh TOC of the
> libraries mikroPascal.Now we have many alternatives in jallib, but many more
> could be added without much difficulty.
>

>    - ADC Library <adc_library.htm> -
>    - CAN Library <can_library.htm>
>    - CANSPI Library <canspi_library.htm>
>    - Compact Flash Library <compact_flash_library.htm>
>    - EEPROM Library <eeprom_library.htm>
>    - SPI Ethernet Library <spi_ethernet_library.htm>
>    - Flash Memory Library <flash_memory_library.htm>
>    - Graphic LCD Library <graphic_lcd_library.htm>
>    - T6963C Graphic LCD Library <t6963c_graphic_lcd_library.htm>
>    - I²C Library <i2c_library.htm>
>    - Keypad Library <keypad_library.htm>
>    - LCD Library <lcd_library.htm>
>    - LCD8 Library <lcd8_library.htm>
>    - Manchester Code Library <manchester_code_library.htm>
>    - Multi Media Card Library <mmc_library.htm>
>    - OneWire Library <onewire_library.htm>
>    - PS/2 Library <ps2_library.htm>
>    - PWM Library <pwm_library.htm>
>    - RS-485 Library <rs-485_library.htm>
>    - Software I²C Library <software_i2c_library.htm>
>    - Software SPI Library <software_spi_library.htm>
>    - Software UART Library <software_uart_library.htm>
>    - Sound Library <sound_library.htm>
>    - SPI Library <spi_library.htm>
>    - USART Library <usart_library.htm>
>    - USB HID Library <usb_hid_library.htm>
>    - Util Library <util_library.htm>
>    - Port Expander Library <port_expander_library.htm>
>    - SPI GLCD Library <spi_graphic_lcd_library.htm>
>    - SPI LCD Library <spi_lcd_library.htm>
>    - SPI LCD8 Library <spi_lcd8_library.htm>
>    - SPI T6963C Graphic LCD Library <spi_t6963c_graphic_lcd_library.htm>
>
>    - Conversions Library <conversions_library.htm>
>    - Delays Library <delays_library.htm>
>    - Math Library <math_library.htm>
>    - String Library <string_library.htm>

>
> Sunish
>
> On Tue, Nov 24, 2009 at 3:17 PM, Sebastien Lelong <
>

> sebastien.lel...@gmail.com> wrote:
> > Hi Matt,
>
> > Having multiple books doesn't seem like a bad idea to me, provided it's
> > consistent. Separating practice (tutorials) and theory (intro, ref) allows
> > readers to focus on what they need.
>
> > That said, I can obviously create a "big book". In theory, I could even
> > pick some pages from Jaluino (external URLs) if needed. In practice, this
> > feature seems not implemented in current DITA-OT.
>
> > So, it's possible. Question now is: what would be the Table Of Content ?
>
> > Cheers,
> > Seb
>

> > 2009/11/24 mattschinkel <mattschin...@hotmail.com>

> >> jallib+un...@googlegroups.com<jallib%2Bunsu...@googlegroups.com>
> >> .

> >> For more options, visit this group at
> >>http://groups.google.com/group/jallib?hl=en.
>
> > --
> > Sébastien Lelong
> >http://www.sirloon.net
> >http://sirbot.org
>
> > --
> > You received this message because you are subscribed to the Google Groups
> > "jallib" group.
> > To post to this group, send email to jal...@googlegroups.com.
> > To unsubscribe from this group, send email to

> > jallib+un...@googlegroups.com<jallib%2Bunsu...@googlegroups.com>
> > .

[funlw65]

About book format and content, I subscribe, mikroe.com is doing a
great job.

Vasi

> >> 2009/11/24 mattschinkel <mattschin...@hotmail.com>

> jallib+un...@googlegroups.com <jallib%2Bunsu...@googlegroups.com>.>>> For more options, visit this group at

>
> http://groups.google.com/group/jallib?hl=en.
>
>
>
> >> --
> >> Sébastien Lelong
> >>http://www.sirloon.net
> >>http://sirbot.org
>
> >> --
>
> >> You received this message because you are subscribed to the Google Groups
> "jallib" group.
> >> To post to this group, send email to jal...@googlegroups.com.
> >> To unsubscribe from this group, send email to
>

> jallib+un...@googlegroups.com <jallib%2Bunsu...@googlegroups.com>.>> For more options, visit this group at
>
> http://groups.google.com/group/jallib?hl=en.
>
>

[mattschinkel]

I think multiple books is the way to go as well. I suggest a "big
book" to remind everyone that we are all one big group (jallib,
jaluino, etc). This big book would just have a larger TOC, copied
from the other books and hopefully would not require much
maintenance.

This big book could then go to the website? or would you prefer many
small books go to the website? whatever is easier for you.


Another suggestion for our book.... I would like to see a word
definition page that would look something like this:

jallib group - a group of people whom create open source libraries for
jalv2
JAL - Just Another Language
jalv2 - a PIC micro compiler built by kyle york
library - blah blah blah


Matt.

On Nov 24, 4:47 am, Sebastien Lelong <sebastien.lel...@gmail.com>
wrote:

> Hi Matt,
>
> Having multiple books doesn't seem like a bad idea to me, provided it's
> consistent. Separating practice (tutorials) and theory (intro, ref) allows
> readers to focus on what they need.
>
> That said, I can obviously create a "big book". In theory, I could even pick
> some pages from Jaluino (external URLs) if needed. In practice, this feature
> seems not implemented in current DITA-OT.
>
> So, it's possible. Question now is: what would be the Table Of Content ?
>
> Cheers,
> Seb
>

> 2009/11/24 mattschinkel <mattschin...@hotmail.com>

> > jallib+un...@googlegroups.com<jallib%2Bunsu...@googlegroups.com>
> > .

> > For more options, visit this group at
> >http://groups.google.com/group/jallib?hl=en.
>
> --

> Sébastien Lelonghttp://www.sirloon.nethttp://sirbot.org- Hide quoted text -