orcmid / doceng Goto Github PK

The construction-structure text files have copyright notices and Apache license grants. For consistency with CC-BY, an attribution statement needs to always be present on how these works can be referenced from derivatives made by ohers.

This does not restrict authors to this with respect to their own copyright works, although there are useful cases of self-attribution being a good accountability practice.

docs/construction/ is an appropriate location for an account of the construction structure. It is an example of what it provides by way of transparency and accountability of the docEng arrangement and how documentation projects might elect to do something equivalent with regard to web-based materials and project artifacts.

The Miser Project has an effort to spiral the construction of of its docs/ and the understanding of the default template and other aspects of the mapping between docs/ and the published orcmid.github.io/miser pages.

Bring those components here and then set those up. The use of spiraling may need to be explained. Add that to the README.md page for the project.

Check out GitHub Community Guidelines

Only mildly recursive, it makes sense that the docEng project be document-engineered.

Set up placeholder docs/ as the published web face for https://orcmid.github.io/docEng

1. setup docs/ as the GitHub Pages authoring folder for docEng web presence.
2. created initial index.md so the web site is workable.
3. create the docs.txt placeholder.

Using an ApacheOpenOffice ODT file, convert it to editable text files using pandoc. Demonstrate and make reproducible.

1. Determine what happens with the document pages and the images.
2. See how to obtain finer-grain text pages from the conversion so that they can be edited easily.
3. Resolve how cross-referencing is reflected and preserved also.

Do these until we have a decent assessment of how an ODT file can be preserved enough but made into suitable editable text forms.

Create a reproducible case in the repository where some can perform the same operations.

Provide something about how to install pandoc and how its usage fits here. Screen capture the command-line operation.

The test file needs to be extended to more cases.

1. additional text decorations
2. Links and cross-references on a page, between pages on a site, and externally - outbound and inbound.
3. Decoration of links with regard to accessibility and other cases.
4. special paragraph forms
5. Images
6. code blocks
7. formulas and ways to have them rendered

Then there needs to be consideration of how pandemic Markdown is handled or not.

On the nfoCentrale web sites, the individual index pages are threaded together and there are connections to construction zones with job jars of tasks and their completions.

There are also catalogs for certain kinds of substructures, viewed as folios of progressions on some topic. Given that GitHub is the platform and it provides for words-in-the-open and code-in-the-open project structures, some of what was employed for nfoCentrale can be managed by other means.

On nfoCentrale, the priority of default.htm over index.htm was used to confine index.htm files to the scaffolding and constructure and using default.htm and other pages as the content being delivered. One is how the web-accessible structure is constructed and maintained. The other is what the structure is "about" with regard to visitors to the sites for information and interaction.

Some adjustments in the docs/ construction structure with the manifests and job jars is pertinent. This will not apply to all folders and directories, depending on their intended function. But we will have it where we need.

Finally, note that this pertains to docEng/docs/ and not necessarily other portions of the GitHub repository and even some portions of docEng/docs/ where a folder might be mechanically generated or used for some other ephemeral purpose.

The page at https://orcmid.github.io/docEng/construction/current/ is a test of MarkDown features using the template that is applicable to rendering of MarkDown in https://github.com/orcmid/docEng/blob/master/docs/

At the moment (2021-02-17T17:18Z), there is no explicit selection of a template. I have named that as "plain." When the template is changed, there will be a different rendering and any comments about the experience with "plain" will be lost.

The idea is to add companion pages that preserve each "current" case with a narrated indelible capture that does not change materially when docs/ templating is replaced. At some point, "current" might depend on more than a template change, and that is a matter for future consideration.

THIS TASK:

1. Provide an https://orcmid.github.io/docEng/construction/plain/ that reflects the tests as now presented in "current."
2. If some screen captures for this exist already, find them and see how to use them.
3. Make proper attribution to the test document(s) that inspired the development of the Markdown for "current."

Whenever a current/ index.md is updated and saved, a copy should also be saved as a raw Markdown file in the folder for the template being exercised. For plain, that would be as plain.index.md.txt. Continue this until done and/or a different template is sued for current.

Add some text

Point out that Issues, Discussion, and Projects are under development
'
Identify the Spiraling approach

To the project

To documentation efforts

The key experiements and the objective

The only Document Engineering for docEng itself is mainly around the use of GitHub and the annotation structure of scaffolding manifests and TODOs. The exemplary document production for docEng iself is just for the web site and the wiki.