Re: Fwd: [dss-x] Markdown code section fixed and rendered as PDF

[Andreas Kuehne <kuehne@trustable.de>]

Hi Chet,

thank you, this pointer helps very much!

And the markdown is the 'authoritative source'! We are really about to
escape from the Word/PDF oligopol!

Greetings,

Andreas

> Hi Andreas,
>
> For an example of an OASIS spec using Markdown as its editorial source,
> take a look at any of the OpenC2 specs. For example, the Language
> Specification currently out for public review is located at
> http://docs.oasis-open.org/openc2/oc2ls/v1.0/csprd01/ . You will find the
> source Markdown and the HTML and PDF outputs.
>
> If you have specific questions, don't hesitate to ask Paul. He has been
> working on the template and processing steps with the editors of OpenC2 and
> by now has a lot of practical knowledge to share.
>
> Best,
>
> /chet
>
> On Sun, Nov 25, 2018 at 12:05 PM Andreas Kuehne <kuehne@trustable.de> wrote:
>
>> Hi Stefan,
>>> [...] we are already working with the OASIS template which is in
>>> development.
>> maybe we get a better idea of the target we are working towards if we
>> can see a 'final' OASIS spec! E.g. I'm still struggeling with the target
>> vision of section numbering. As far as I understand MarkDown there is no
>> section numbering but many tools provide it somehow.
>>
>> I made a quick check with the specifications moved to standard recently.
>> But most of them has a doc / docx file included, none published a
>> markdown file.
>>
>>> As we have chopped the main part of the spec into salami
>>> slices that are in the worst case nerver where we think they are
>>> (regardless of word or markdown) the most interesting part to me
>>> personally is have my fingers understand where to be expected to type
>>> what focused on content and where to keep the fingers still.
>>>
>>> Maybe we should pull the many snippets back into main code and simply
>>> target the code matching some simple one line tags into the spec
>>> prose everytime we push a change?
>> Hmm, maybe we have the same vision how to work with the document!
>>
>> As my brain is somewhat cumbersome I did implement the Word-based
>> approach to MarkDown:
>>
>> - Edit one single document
>>
>> - Let the generator manage the 'Data Structure Models'
>>
>> - Mark the editable / preserved parts in the  'Data Structure Models'
>> ('green' sections)
>>
>> - build a 'final' version without the 'green' sections and markups for
>> publication
>>
>>> The green regions in word already got me paralyzed (because of the
>>> magic or not so magic formating word left the poor editor with in the
>>> final pre-publication stage); if you guys want to keep the new magic
>>> variant with some heavily attributed HTML tag inside the markdown
>>> maybe this works after some gettng used to?
>> It's just a technical handle to detect & preserve the editable parts.
>> Other variants may be possible to implement. But the identification of a
>> section remains the major part of it.
>>> All the best,
>>> Stefan
>>>
>>>
>>> Am 24.11.18 um 18:59 schrieb Andreas Kuehne:
>>>> Hi all,
>>>>
>>>>
>>>> Detlef raised the question of a MarkDown template for OASIS
>>>> specifications.
>>>>
>>>> Maybe that's just a trained expectation ... the RFC did a good job even
>>>> without a shiny logo. But if it boosts the acceptance of our stuff, I'll
>>>> go with any shiny layout!
>>>>
>>>> Are there OASIS official standards out in a MarkDown-only style?
>>>>
>>>>
>>>> Greetings,
>>>>
>>>>
>>>> Andreas
>>>>
>>>>
>>>>
>>>> -------- Weitergeleitete Nachricht --------
>>>> Betreff:     AW: [dss-x] Markdown code section fixed and rendered as PDF
>>>> Datum:     Thu, 22 Nov 2018 07:17:42 +0100
>>>> Von:     detlef.huehnlein@ecsec.de
>>>> An:     'Andreas Kuehne' <kuehne@trustable.de>
>>>>
>>>>
>>>>
>>>> Hi,
>>>>
>>>> yes, the "OASIS Template" needs some more polishing to produce
>>>> something, which in the end looks like an OASIS Standard. Could OASIS
>>>> help here?
>>>>
>>>> BR,
>>>> Detlef
>>>>
>>>> -----UrsprÃngliche Nachricht-----
>>>> Von: dss-x@lists.oasis-open.org <dss-x@lists.oasis-open.org> Im Auftrag
>>>> von Andreas Kuehne
>>>> Gesendet: Mittwoch, 21. November 2018 22:53
>>>> An: dss-x <dss-x@lists.oasis-open.org>
>>>> Betreff: [dss-x] Markdown code section fixed and rendered as PDF
>>>>
>>>> Hi,
>>>>
>>>>
>>>> see attached the PDF output of the markdown version. The
>>>> 'single-line-code' flaw pointed out by Ernst Jan was an artifact of the
>>>> Word->Markdown conversion.Fixed now.
>>>>
>>>> I discussed the pro and cons of MarkDown and Word with Stefan. My major
>>>> aspects are
>>>>
>>>> - November nearly over and no version ready
>>>>
>>>> - Word is an capricious beast
>>>>
>>>> - MarkDown allows reuse of content in Swagger
>>>>
>>>>
>>>> Do you see other relevant topics?
>>>>
>>>>
>>>> Greetings,
>>>>
>>>>
>>>> Andreas
>>>>
>>>>
>>>>
>>>
>> --
>> Andreas KÃhne
>> phone: +49 177 293 24 97
>> mailto: kuehne@trustable.de
>>
>> Trustable Ltd. Niederlassung Deutschland Gartenheimstr. 39C - 30659
>> Hannover Amtsgericht Hannover HRB 212612
>>
>> Director Andreas KÃhne
>>
>> Company UK Company No: 5218868 Registered in England and Wales
>>
>>
>>

-- 
Andreas KÃhne 
phone: +49 177 293 24 97 
mailto: kuehne@trustable.de

Trustable Ltd. Niederlassung Deutschland Gartenheimstr. 39C - 30659 Hannover Amtsgericht Hannover HRB 212612

Director Andreas KÃhne

Company UK Company No: 5218868 Registered in England and Wales

Attachment: smime.p7s
Description: S/MIME Cryptographic Signature