-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdoceng.txt
289 lines (217 loc) · 13.3 KB
/
doceng.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
docEng.txt 0.0.9 UTF-8 dh:2023-11-02
*---|----1----|----2----|----3----|----4----|----5----|----6----|----7----|--*
nfoWare/nfoWorks docEng Document Engineering Project
====================================================
<https://github.com/orcmid/docEng>
<https://github.com/orcmid/docEng/blob/main/docEng.txt>
PATTERNS, PRACTICES, AND TOOLS FOR DOCUMENT ENGINEERING
DOCUMENT ENGINEERING UNDER GITHUB
---------------------------------
docEng is a collection of practices, utilities and software components.
The patterns are all around Document Engineering involving GitHub in
some capacity.
There is attention on how to structure for documentation of software
projects. There is attention on how to structure web-site organization
for development and for documentation. And there is attention to the
processing of document representations in various forms.
The determination and calibration of document-processing interop is a
separate project, currently in hibernation: orcmid/DocInterop on GitHub.
Document Engineering patterns are developed with implementations found
in other GitHub projects. The Document Engineerng application to docEng
itself is a flavor of a self-referential pattern.
MANIFEST
docEng.txt
this manifest and job-jar file
docs/
source of GitHub Pages documentation for docEng and accessible at
<https://orcmid.github.io/docEng/>
LICENSE.txt
The open-source software license that applies to the entire
GitHub orcmid/docEng project except where stated otherwise.
NOTICE.txt
Notice that applies with respect to particular components in
the docEng repository and any dependencies they might have.
.gitattributes
A declaration of file attributes for use in Git repositories of
the nfoTools source code.
.gitignore
A declaration of artifacts to be ignored and excluded from Git
repositories, applying to working files that are not part of the
managed archive materials
README.md
The customary README for GitHub projects
*---|----1----|----2----|----3----|----4----|----5----|----6----|----7----|--*
Copyright 2021-2023 Dennis E. Hamilton
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*---|----1----|----2----|----3----|----4----|----5----|----6----|----7----|--*
ATTRIBUTION
Hamilton, Dennis E. Document Engineering under GitHub. Text file
docEng.txt version 0.0.9 dated 2023-11-02 available on the Internet as a
version of <https://github.com/orcmid/docEng/blob/main/docEng.txt>
TODO
* Fix .gitignore to ignore FrontPage artifacts in case they occur here.
* URGENT: Add the Microsoft OOXML formats to .gitattributes as binaries.
* Edit GitHub Readme.md to describe this project.
* Explain what Document Engineering is.
* Complete any customization of the front-porch of the project's repository:
License
Notice
.gitignore
.gitattributes
* Start using orcmid/docEng Issues, Discussion, and Projects for operation
in the open
* CRITICAL QUESTION: Will we use the nfoCentrale Construction Structure and
Construction Materials scheme here, and if so, how do we deal with
conversations about other forms of docEng. Reconcile this with the
originally-intended scope for docEng.
* Get into the GitHub templates for documentation and deal with it in the
Construction Materials of the docEng site. See
<https://github.com/orcmid/nfoTools/issues/8>.
* The use of FrontPage for GitHub Pages is not the same as the site-server
model. There is no separation between authored and published. With
FrontPage over a GitHub Pages folder (e.g., a docs/) there is no sepaation
of design-time and server publishing. Design-time operations are
immediately publised once committed to the GitHub projct. I'm fine with
that. It just needs to be clear in how I speak about it.
* Find a clean way to talk about the *authored" documentation and the
*authoring" source that is published to be the documentation. Need some
nomenclature that I don't keep tripping over. [from Miser Project]
* In the construction of DocEng docs/, there needs to be a distinction
between construction and management of the web materials versus job jar
and diary regarding the subject matter, not the site construction,
although that becomes rather "meta" as well, here. There are clearly
editorial cross-overs, and it needs to be treated as a pattern here.
* The default rendering, with no template, provides reflow in the manner
required for Miser Project documentation. How to ensure that with any
of the provided themes remains to be understood. [from Miser Project]
* Find a theme that supports reflow. The Pages templates do not seem to
provide for that. [from Miser Project]
* If a theme is customized, determine where and how that works. [from
Miser Project]
* I am trusting that this material is current as of 2019-11-20:
<https://help.github.com/en/github/working-with-github-pages/getting-started-with-github-pages>
* I have been employing in-line HTML comments to account for versioning
of markdown pages here. I don't know if there is something better, using
YAML or something. [from Miser Project]
* Work through all of the feature cases of GitHub Markdown to see what
works with the default template. Use construction/test/ or example/
for that. [from Miser Project]
* Create a test document (set) that demonstrates the main Markup
provisions. [from Miser Project]
* Create a folder (i.e., plain/ that carries captured images of the
current test/demo document under the default template). [from Miser
Project]
* Make a template for the index.md source pages. [from Miser Project]
* Add a forensics folder on web-site and authoring, plus trouble-shooting,
reverse-engineering, etc. Maybe this belongs on docEng.
[from Miser Project]
* Confirm preservation with pre-HTML5 browsers, such as Internet Explorer.
[from Miser Project]
* The "improve this page" and edit/master link requires being logged-in to
GitHub. We need a way to suppress that. [from Miser Project]
* The folio system is a bit different here. There can be a counterpart in
how pages and their assets are in folders. The idea of version sequences
does not quite work unless we take it to a lower level. The use of insert
pages might have no counterpart here. Having the effect would take
copying. [now that FrongPage is being used, the design-time actions are
now available. The dealing with folio depth and URL-shortening is
illustrated in nfoTools/tools.] [from Miser Project]
* GitHub, and use of Git, provides a valuable history and provenance system.
It requires access to such "document forensic" tools and doesn't support
removed (? what phrase did I intend here) prints of pages the way I have
desired. I think this is about wanting to always have material be
printable and having its provenance/origin be explicit in it.
[from Miser Project]
* I need docEng of the docEng/docs about docEng. This seemingly recursive
case needs to bottom out on some ground case.
* With regard to web-published documentation, this seems to be the place
for wingnut. Or do I really need a wingnut project? It certainly has
its own blog(s), etc., but that does not prevent it from being under
docEng.
* On the other hand, it might make more sense to have nfoCentrale
as a GitHub project, just like that web has been under VSS. Must think
this through. Wingnut is about blogs and not web sites, but it is a
portion of a larger project. But there are individual webs under IIS
in the nfoCentral publishing model, even though they map to subfolders
on A2 Hosting's nfoCentrale.com site. So they are managed individually
and updates published individually.
* The nfoCentrale publishing model does rely on the site-server model to
distinguish between authoring (in FrontPage) and publishing (via FTP from
shared VSS of final-form HTML and assets).
* Do I really want to rescue nfoCentrale.com? I should subdivide it then,
and I should probably keep the projects private.
* Can a project be published (under orcmid.github.io) even when the
authoring repository is private? I need to look into that.
* Can I rescue an nfoCentrale.com web site into a Hugo site? What will
have to change? COOL. GitHub publishes .md files to .html, not .htm,
so I can have my construction structures and other files side-by-side.
* With regard to granularity, it is clear I should not have repositories
larger than the domains that map to nfoCentrale.com. I will not keep
the separate domains (or at least not most of them), but I can make them
separate GitHub projects and isolate the authoring. Whether I publish
to individual docs or into a larger one is a separate consideration.
I am conflicted about that. I don't want to think of GitHub having to
republish large chunks or even an entire mega-doc folder.
* I need to think through the nfoCentral federation of sites to a rescue
and preservation on GitHub.
* I also need to find a way to make headway on important nfoTools, Miser,
and docEng efforts without getting badly detoured.
* A goal for breaking the logjam, without floating all the logs at once,
is employment of Hugo for orcmid.github.io/docEng itself and going on
from there. Hugo will come under tools/ and maybe dev/ here. There also
may need to be a wingnut preservation as demonstration of the rescue and
also introduction of Hugo for it.
* I assume that a repository that is specifically for a web site could have
GitHub Pages be at the root. It makes the README be a little weird,
except it can serve as the front porch. I should try that. I need to be
careful about its maintenance as a Hugo site then. Yes, that's weird.
Obviously needs to be tried with wingnut and I need to get my head around
this case. I'm just attempting to save a level of nesting for a project
that is entirely about a web site.
* In this case, the clone is a Hugo publishing folder, not the Hugo
authoring folder. That breaches wanting to have the authoring be under
Git. I must adjust the model for that. It looks like the Hugo site
should be a project and its public should be the GitHub pages. There is
a small matter of customization of other aspects and how that syncs with
Hugo updates. These are customizations of dependencies. I need to figure
out how that can work.
* This is complicated. I have to figure out what not to clone yet I can
customize and preserve in GitHub. I don't think I should be using
.gitmodule in this. I then need to deal with dependency/customization
management. My head hurts and I will stop for now.
* I need some simple rescue efforts in Hugo.
* See docs.txt for more on skills and tools, including translation as well
as exfiltration of web sites/content.
* Here's a related/relevant skill item,
<https://twitter.com/vardi/status/1523069742076022785>.
* Internationalization (i18n) and accessibility (a11y) are particularly
relevant in document engineering and applicable to docEng docs/. There
is a cross-over with nfotools/docs (cf.) and this needs to be navigated.
Since we propose to use Hugo for document engineering of orcmid.github.io,
that all needs to be sorted out.
* Many nfoCentrale add-on domains are being retired and only replaced by
their subdomains. This is an interesting process and might be managed
from here or orcmid.github.io/wingnut. I am not clear about this.
*---|----1----|----2----|----3----|----4----|----5----|----6----|----7----|--*
0.0.9 2023-11-02T15:57Z Introduced the meta construction vs content issue
0.0.8 2023-10-28T17:15Z Urgent TODO on OOXML .gitattributes
0.0.7 2023-10-28T17:03Z Reflect refactoring and availability of a FrontPage
case here.
0.0.6 2022-12-22T17:01Z Manage TODOs, ponder a11y.
0.0.5 2022-10-13T16:12Z Review of TODOs, pondering of approach here.
0.0.4 2022-04-29T17:31Z Pondering web-site authoring collaboration models
and how to handle/incorporate rescuing sites to Hugo.
0.0.3 2021-10-29T22:31Z Smooth, replace "master" with "main"
0.0.2 2021-10-17T21:30Z Identify needd to change "master" to "main" here.
0.0.1 2021-09-05T17:12Z Replace nfoTools boilerplate with docEng material.
0.0.0 2021-02-15T00:35Z Initial placeholder of the top level manifest and
job jar.
***** end of docEng.txt *****