Coder Social home page Coder Social logo

reference-en's Introduction

Reference-en

Reference-en is the repo for the Language Reference documentation of the Arduino syntax in English. All the Reference terms files are in AsciiDoc format.

Thank you for taking the time to contribute to Arduino content, this is really helpful to the whole Arduino Community. If you want to learn more about how to contribute to this project, please check this step by step tutorial.

Content Creation and Editing

If you want to contribute new content, create a new file (with any text or code editor) and save it as .adoc. Do not use parenthesis or any special character in the file name. In reference-en/AsciiDoc_sample/AsciiDoc_Dictionary you will find an overview of the AsciiDoc syntax. This includes Titles, Text, Links, Images, Tables, Code and various embeds (video, slideshow, audio, and code). You can see it rendered here.

If you want to contribute to the Language Reference or edit existing content, you can find two templates in reference-en/AsciiDoc_sample/Reference_Terms:

Please note that every Reference file should include at least a Description, some Example Code, and links to other relevant info (See Also section).

If you need to add images to the Asciidoc please create a folder called attachments in the same directory as the Asciidoc file. Images can be saved in SVG and PNG format, max size 200KB.

Contribute Content on Github

If you are not familiar with Git you can contribute content directly on Github via their online interface. We put together a short Tutorial to show you how - CHECK IT OUT!

You can also follow this guide (written by the Github team) to learn how to edit an .adoc file and propose a file change to the Arduino team. When suggesting a change, please follow the guidelines described in the Reference template files.

Submitting a pull request

We are glad you want to contribute to the Arduino Reference: that’s the best way to help the community.

Your contribution is adding or modifying existing code or full descriptions, please always refer to an existing issue or open a new one before contributing.

Folder Structure

reference-en
├─ AsciiDoc_sample
│   ├── AsciiDoc_Dictionary
│   │   ├── AsciiDoc_Template-Dictionary.adoc
│   │   └── attachments
│   └── Reference_Terms
│       ├── AsciiDoc_Template-Parent_Of_Entities.adoc
│       ├── AsciiDoc_Template-Single_Entity.adoc
│       └── attachments
├── Language
│   ├── Functions
│   ├── Structure
│   └── Variables
├── LICENSE.md
└── README.adoc

Within the Language folder, the file tree follows the same structure as in the Arduino Reference webpage

License

Please note that your contribution to the Arduino Reference is licensed under a Creative Commons Attribution-Share Alike 3.0 License. see https://creativecommons.org/licenses/by-sa/3.0/

reference-en's People

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

reference-en's Issues

Status of this repo?

It appears that this repository is the source of (a part of) the docs on arduino.cc. However, it hasn't seen any updates in a while, and I do believe doc changes have been made. Can someone clarify the status of this repo?

Is it possible to access the old Language Reference pages?

In the process of fixing regressions, I'm frequently wanting to look at the old reference pages so that I can port the changes here.

I did find that I could access the pre-change version of one page by using the previous URL:
https://www.arduino.cc/en/Reference/AttachInterrupt/

but with other pages that doesn't work because they redirect to the new page, for example:
https://www.arduino.cc/en/Reference/Constants
redirects to
https://www.arduino.cc/reference/en/language/variables/constants/constants

So, as a side note, I suspect that actually the lack of a redirect on https://www.arduino.cc/en/Reference/AttachInterrupt/ may be a bug.

Question: Understanding what this documentation affects

Hi, I am new to project collaboration, and periodically have modifications/additions I'd like to make to the Arduino documentation, but I never knew how to do so.

I want to know: if I fork, modify, and do a pull request on this documentation repository, what documentation does it affect?
ie:

  1. Arduino Website Documentation? (http://arduino.cc/en/Reference/HomePage)
  2. Local IDE documentation on future downloads? (accessed via IDE help menu)
  3. anywhere else I should know?

Thanks. I would like to make contributions to Arduino where able, and I think I finally have a decent idea how to do so.

Side Question: anyone know what the process is for getting a new library included as part of the Arduino core?

List of broken links

Auto-generated list of broken links for reference-en as of 2020/04/27 08:41:04 (GMT)
0 total:

This issue will auto close once all links are working.

Correct see also section in every page

Now the "see also" section will be autogenerated with the terms in the same subcategory, even if the page doesn't have the "see also" section at all.

So the editor should add the "see also" section only if he wants to add terms from other subcategories or examples or definitions.

Let's remove any duplicate from the pages
I already fixed the terms for the "functions" part

Specify data types in function definitions

I suggest that the types of arguments and return values be specified in the documentation. For example instead of:

Syntax

digitalRead(pin)

Parameters

Returns

HIGH or LOW

State the data types, eg.

Syntax

int digitalRead(byte pin)

Parameters

Returns

HIGH or LOW

You shouldn't have to muck around looking in the source just to find if the argument is a byte or an int, or what type the return value is.

Also in this particular case, couldn't "parameters" be explained? eg.

Parameters

pin: The pin number to read from, on the Arduino board. This is probably not the pin number on the actual processor chip.

Contribution guidelines make it difficult for people to contribute

From https://github.com/arduino/reference-en/blob/master/README.adoc:

please add one or more tests that prove that your contribution is good and is working as expected

Are you serious about this? I think it will be great when you get Drone working but I can't imagine what tests the average contributor would need to add with documentation fixes or additions.

Be sure to use go vet and go fmt on every file before each commit: it ensures your code is properly formatted.

Is this correct? It seems strange to require the use of a Go formatting tool.

Also, for your contribution to be accepted, everyone of your commits must be "Signed-off". This is done by commiting using this command: git commit --signoff

Is that really necessary? It just seems like it will discourage people from being able to do quick typo fixes. I have no problem with using Git from the command line but the majority of Arduino users consider even using the simplified GitHub web interface intimidating. If you throw a bunch of extra requirements on they'll either decide it's not worth the effort to contribute or just ignore the contribution rules.

Reference missing mention of constants A0, A1, ...

As I mentioned along with some other stuff on the forum, the analog input pin constants are not mentioned in the Arduino reference - not under Constants and not in analogRead.

But actually, I'm unclear on how they are used. I have an Uno and the constant A0 has the value 14. The example AnalogReadSerial uses this constant to read the value: int sensorValue = analogRead(A0);
However, the analogRead reference page says:

pin: the number of the analog input pin to read from (0 to 5 on most boards, 0 to 7 on the Mini and Nano, 0 to 15 on the Mega)

So which is it? Is the reference page plain wrong, or are A0 and 0 equivalent for analogRead?

Demonstrate return type format in the sample

I notice the formatting of return types documentation is very inconsistent from page to page throughout the documentation. The sample page should establish a formatting standard for return types but currently it only demonstrates how void functions should be documented.

Remove the Asciidoc example directory

this pollutes the repo with information that should be either linked from the web in the readme or in a separate repo

and convert the .md files to .adoc files as well.

m

AsciiDoc_Template-Single_Entity.adoc doesn't match the reference pages in the repository

AsciiDoc_Template-Single_Entity.adoc is missing the first section that is found in all the other reference pages in this repository. For example, https://raw.githubusercontent.com/arduino/reference-en/master/Language/Structure/Comparison%20Operators/lessThanOrEqualTo.adoc, which was created 9 days ago so I have to assume it is in the correct format, starts with:

---
title: "<="
title_expanded: Less Than or Equal To
categories: [ "Structure" ]
subCategories: [ "Comparison Operators" ]
---

but nothing of that sort is found in the example.

List of broken links

Auto-generated list of dead links as of 2017/11/06 10:14:10 (CEST)
14 total:

expected '}' before 'else' Return Arduino [C]

Language/Structure/Control Structure/return.adoc

[source,arduino]

int checkSensor(){
if (analogRead(0) > 400) {
return 1;
} // <-- Added } closing return1; (if function).
else{
return 0;
}
}

Syntax error, error: expected '}' before 'else'

Error in Example Code for Break an Continue Refrence

The Example Code in Reference pages both for Break and Continue is wrong.
On each pages the statement digitalWrite(PWMpin, x); shoud be replaced by an analogWrite(PWMpin,x); statement, since x goes from 0 to 255.

Issues with AsciiDoc_Template-Dictionary.adoc

README.adoc claims:

In reference-en/AsciiDoc_sample/AsciiDoc_Dictionary you will find an overview on the AsciiDoc syntax. This includes Titles, Text, Links, Images, Tables, Code and various embeds (video, slideshow, audio and code). You can see it rendered here.
Several of the items in this file do not correctly render:

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.