View unanswered posts | View active topics It is currently Sun Jul 22, 2018 3:49 pm



Reply to topic  [ 3 posts ] 
Documentation Source Separation 
Author Message
Moderator
User avatar

Joined: Tue Jan 15, 2008 2:31 pm
Posts: 15162
Location: Home sweet home!
Currently there are a lot of docs in the firmware. Many of them are binary files and I don't like committing against them in the firmware repo. Additionally, I don't like having to merge people's work into the firmware when it isn't really firmware related. We need to make some changes:

  • Some of the docs should stay in the firmware docs dir, but others should come out.
  • Some should stay on OD formats
  • Some should be changed to markdown
  • Some should be in LaTex

And maybe other changes?

This seems like a good time to split out some of the documents to different places and figure out which formats each should be available in and add licensing to them. Currently none have licensing and I would very much like at least some of the FreeEMS docs to be non-free. The reason for that is to maintain a single golden source of them, right here. Having 50 copies, 49 of which are out of date is not helpful. Backups will be taken and a mechanism for mirroring provided, but the source must be here, and it must be singular. I guess it might be a good idea to header the docs with "If you're not viewing on FreeEMS.org, the original version of this document can be found here!" statement as seen on many sites that get plain copied.

The trouble is, I have no knowledge of closed source licenses suitable for interface documentation such as the comms core spec. Some docs, such as that one, should not even be modified by others, however distribution in some ways should be permitted regardless of that. This needs to be executed very carefully to ensure it works as intended and doesn't backfire as ms2e 3.2's license change just did :-/

This has been on my mind for a long time, I've just not found time to sort it out until now.

Now, which files are there? Let's take a look and present a full listing here and a comment on each deciding what happens to it. This section is fully up for discussion, please comment. I've created an issue here to track progress on it: http://issues.freeems.org/view.php?id=397

Belongs in firmware as is:
Code:
./calculators/dwellTime.ods
./calculators/injectorDeadTime.ods
./calculators/warmUpCurve.ods
./MissingTeethValidCombos.ods
./MainTableValidSizes.ods
./Doxyfile
./git/config
./licenses/gpl.template.bash
./licenses/gpl.template.c
./licenses/gpl.template.h
./licenses/gpl.v3.full.txt


Belongs in firmware or deleted, but maybe with format change. Needs to be cleaned up and cleared out or put into production:
Code:
./dev/release.pre.tests.txt - needs to move into a formal release procedure document, probably in markdown
./dev/release.procedure.txt - updated, needs to be formalised.
./dev/serial.imp.issues.txt - updated, but needs to be transferred to the issue tracker
./dev/tasks.txt - updated, but needs to be transferred to the issue tracker
./interface/FreeEMS-DDL.mm
./interface/FreeEMS-DDL.xsd
./interface/FreeEMS-XML2C.xsl
./interface/IFreeEMS-Vanilla-DDD.xml
./interface/IFreeEMS-Vanilla-Specific-Serial-Protocol.odt
./interface/DataMapStructure.odg - what is this?
./interface/draftsAndIdeas/basicDatalog.txt
./interface/draftsAndIdeas/DatalogExample.js
./interface/draftsAndIdeas/IFreeEMS-Vanilla-Interface-Data-Map.js
./interface/draftsAndIdeas/IFreeEMS-Vanilla-Interface-Packet-Descriptions.js
./interface/draftsAndIdeas/IFreeEMS-Vanilla-Interface-Structure-Descriptions.js
./interface/draftsAndIdeas/SettingsExample.js
./interface/draftsAndIdeas/some.good.default.data.and.curves.xml
./interface/draftsAndIdeas/structure.relationships.description.txt


Needs to move to a different repository. Some should become latex and have an HTML version be linked from the firmware and itself link to the latex source:
Code:
./FreeEMS-PinAssignment-XDP512.ods - hardware guide, nothing to do with firmware, except that firmware defines how it should look, migrate to another format or keep it and change format somewhat inside?
./FreeEMS-HardwareStandards.odt - formal spec, belongs in latex for both html and pdf
./FreeEMS-FirmwareSerialImplementation.odt - white paper style, belongs in latex for both html and pdf
./FreeEMS-MemoryManagement.odt - exists in latex, remove?
./FreeEMS-SerialProtocolCoreSpecification.odt - exists in latex, remove?
./latex/FreeEMS-MemoryManagementScheme.tex
./latex/FreeEMS-SerialProtocolCoreSpecification.tex
./latex/FreeEMS-template.tex - keep this in the docs repo only
./FreeEMS.mm - maybe not latex for this one, perhaps something else like PlantUML
./FreeEMS-MinToMaxBasicConfigurations.txt - hardware design guidelines to be moved into latex
./latex/logos/diyefi.eps
./latex/logos/diyefi1.png
./latex/logos/diyefi2.png
./latex/logos/freeems.eps
./latex/logos/freeems.png
./latex/README


I'm hoping that we can link to web images for builds as well as local ones? or even web include images in pdfs?

Migrated all of this to a migrate directory ready for the move. More work to be done.

Fred.

_________________
DIYEFI.org - where Open Source means Open Source, and Free means Freedom
FreeEMS.org - the open source engine management system
FreeEMS dev diary and its comments thread and my turbo truck!
n00bs, do NOT PM or email tech questions! Use the forum!
The ever growing list of FreeEMS success stories!


Thu Nov 17, 2011 1:50 am
Profile WWW
LQFP112 - Up with the play

Joined: Sat Apr 24, 2010 1:42 am
Posts: 119
Location: New Zealand
How do we know which format (Latex/OD/Markdown) should be used for different types of documents?


Thu Nov 17, 2011 2:04 am
Profile
Moderator
User avatar

Joined: Tue Jan 15, 2008 2:31 pm
Posts: 15162
Location: Home sweet home!
So far, spreadsheets stay in open office format, and all the formal specification documents which are formal in style belong in latex. markdown is suitable for more casual docs, or so it seems. I think .txt files have a limited future in that repo.

I see the following being used in future: .md .ods .plantuml .tex

I guess the rules would be something like:

Spreadsheet = ODS
Needs to be read in a text editor and optionally displayed as HTML = MD
Needs to be published formally as a document and displayed as HTML = TEX
Diagrams should be written in some sort of textual source format such as plantuml

Fred.

_________________
DIYEFI.org - where Open Source means Open Source, and Free means Freedom
FreeEMS.org - the open source engine management system
FreeEMS dev diary and its comments thread and my turbo truck!
n00bs, do NOT PM or email tech questions! Use the forum!
The ever growing list of FreeEMS success stories!


Thu Nov 17, 2011 2:16 am
Profile WWW
Display posts from previous:  Sort by  
Reply to topic   [ 3 posts ] 

Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
cron
Powered by phpBB® Forum Software © phpBB Group
Designed by ST Software for PTF. ColorizeIt.