proposal for documenting fields and files

[ouabache]

initial proposal

[ubruhin]

Thanks for working on this 😃

My thoughts so far:

• I would move the basic S-Expressions documentation (general structure, charset, EOL character, formatting, ...) into a separate page (e.g. called "File Format") since it's not specific to libraries. Or even move everything into this new page, so all *.lp files are documented in one page to avoid clutter up basic documentation of libraries and projects.
• There are a lot of empty lines - please only use 1 empty line to separate paragraphs and 2 empty lines to separate chapters.
• I don't really understand the right column of the file format documentation 😉 What are the LP_* terms used for?
• I have not much experience with documenting file formats, but maybe it would make sense to use something like BNF for that? @dbrgn @rnestler, any opinion about that?

[dbrgn]

BNF (or EBNF) would work, but since we don't actually parse the file format spec, we don't benefit that much from a structured format. On the other hand, the BNF would give us re-usable types, so a (pos x y) type only needs to be defined once and can then be re-used.

@rnestler what do you think?

[ouabache]

The right column was my attempt to cover all the use cases: 1) A field must be defined only one time 2) A field must be defined but can have more than one definition 3) A field may be defined zero or one time only 4) A field may be defined zero or multiple times. The LP_ names are simply to have a name that you can refer to for that field from the documentation I don't have a lot of experience with file formats either. If I see an example then I can understand it easier than trying to parse some formal definition. I also put in a pull request for 10 bga packages for the LibrePCB_Base library.

…

On Sat, Oct 5, 2019 at 4:34 AM U. Bruhin ***@***.***> wrote: Thanks for working on this 😃 My thoughts so far: - I would move the basic S-Expressions documentation (general structure, charset, EOL character, formatting, ...) into a separate page (e.g. called "File Format") since it's not specific to libraries. Or even move everything into this new page, so all *.lp files are documented in one page to avoid clutter up basic documentation of libraries and projects. - There are a lot of empty lines - please only use 1 empty line to separate paragraphs and 2 empty lines to separate chapters. - I don't really understand the right column of the file format documentation 😉 What are the LP_* terms used for? - I have not much experience with documenting file formats, but maybe it would make sense to use something like BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form> for that? @dbrgn <https://github.com/dbrgn> @rnestler <https://github.com/rnestler>, any opinion about that? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#518?email_source=notifications&email_token=AAKX3XEGHOHDPINHL26K2KLQNB3VJA5CNFSM4IXXGQ3KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEANQMPA#issuecomment-538641980>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAKX3XFU36342FLMEHM2HUDQNB3VJANCNFSM4IXXGQ3A> .