Re: handling description markup/semantics for SQLite3 "output"?
Adrian M Negreanu <[email protected]> Mon, 10 Jul 2017 19:05:02 +0300
| Newsgroups | gmane.text.doxygen.devel |
|---|---|
| Message-ID | <CAGV5d_0g6bhvBm7J6Gky-0dTgYyFppG=GoZNLh-xehCRY8aypA@mail.gmail.com> |
--===============1663581463318645070== Content-Type: multipart/alternative; boundary="001a113cf13ee8550a0553f8bead" --001a113cf13ee8550a0553f8bead Content-Type: text/plain; charset="UTF-8" Hi, I think, from the gist you posted, that your use case needs to extend the current schema so that the elements you see in the xml will also be found in sqlite3. So you'll need a `page` table and add a generateSqlite3ForPage that fills in that table. Tbis way the semantic you mentioned previously would be provided by the new table/attribute. On Jul 10, 2017 18:57, "Travis Everett" <[email protected]> wrote: Hi again Adrian, I agree with what you've said, but I think that only holds when the detaileddescription database field holds a *single* format. An example of the input/output I'm working with might be more useful than my initial description: https://gist.github.com/abathur/b3d3d258853 03eb216e0ffa2d2604034 In this example, you can see that the string going into the database contains three different formats: an HTML header, plaintext markup, and Doxygen commands. Context: `generateSqlite3ForPage` is one of the parts of sqlite3gen that I'm refining as I work on a broader project that generates Doxygen-ready source files and markdown pages from a large Sphinx/RST corpus. Cheers, Travis On Sun, Jul 9, 2017 at 11:48 PM, Adrian M Negreanu <[email protected]> wrote: > Hi Travis, > > The format of the description is dictated by the client's needs. Or in > other words, where that description is used. > > I'm using it from python scripts which makes it easy to parse the current > plain text. > > This brings me to the question : why do you need another format, say (A), > when you'll already have to parse the plaintext format to extract the > semantic needed by (A) ? > > One reason for adding (A) is "it's easier for the client to use/parse", > which brings me again, to the first part : what client do you have ? > > Regards > > > On Jul 10, 2017 3:21 AM, "Travis Everett" <[email protected]> > wrote: > > All, > > I'm resuming work on refining the experimental SQLite3 output. I've run > into a pretty obvious quandary that I was blissfully ignorant of: > > Before output-format-specific conversion, it looks like detailed > descriptions can include (at least) a mix of HTML and raw text that still > contains doxygen commands (I haven't gone fishing, but my guess is that > markdown gets translated down to HTML, and output translators are > responsible for the rest). > > When it's being served by an SQL database, it doesn't seem like there's an > "obvious" or "expected" format for presentational/semantic markup embedded > in the detailed description. I was a bit surprised to find plaintext > Doxygen commands present at this stage. > > I'm curious if anyone has thoughts on how to handle these. The best three > paths forward seem to be: > > - Saving it as XML. I'm not keen on this since it significantly raises the > bar on using the sql output, and would require either updating all of the > descriptions in place, or parsing them into a more useful form on each use. > - Saving an opinionated plaintext translation. This would retain simple > usability and avoid the update-all-descriptions or constantly-reparse > issues, as long as consumers can live with the format ;) > - Some active, user-configurable translation method (probably translate to > XML and then call a user-defined translator script as with input filters. > *not sure how complex this would be or where to start; may be getting out > of my depth. > > Thanks for any direction, > Travis > > ------------------------------------------------------------ > ------------------ > Check out the vibrant tech community on one of the world's most > engaging tech sites, Slashdot.org! http://sdm.link/slashdot > _______________________________________________ > Doxygen-develop mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/doxygen-develop > > > ------------------------------------------------------------ ------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________ Doxygen-develop mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/doxygen-develop --001a113cf13ee8550a0553f8bead Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"auto">Hi,<div dir=3D"auto">=C2=A0I think, from the gist you pos= ted, that your use case needs to extend the current schema so that the elem= ents you see in the xml will also be found in sqlite3.<br></div><div dir=3D= "auto"><br></div><div dir=3D"auto">So you'll need a `page` table and ad= d a generateSqlite3ForPage that fills in that table.</div><div dir=3D"auto"= >Tbis way the semantic you mentioned previously would be provided by the ne= w table/attribute.</div></div><div class=3D"gmail_extra"><br><div class=3D"= gmail_quote">On Jul 10, 2017 18:57, "Travis Everett" <<a href= =3D"mailto:[email protected]">[email protected]</a>> w= rote:<br type=3D"attribution"><blockquote class=3D"quote" style=3D"margin:0= 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class=3D"quoted= -text"><div dir=3D"ltr"><span style=3D"font-size:12.800000190734863px">Hi a= gain Adrian,=C2=A0</span><div style=3D"font-size:12.800000190734863px"><br>= </div><div style=3D"font-size:12.800000190734863px">I agree with what you&#= 39;ve said, but I think that only holds when the detaileddescription databa= se field holds a=C2=A0<i>single</i>=C2=A0format.</div><div style=3D"font-si= ze:12.800000190734863px"><br></div><div style=3D"font-size:12.8000001907348= 63px">An example of the input/output I'm working with might be more use= ful than my initial description:=C2=A0<a href=3D"https://gist.github.com/ab= athur/b3d3d25885303eb216e0ffa2d2604034" target=3D"_blank">https://gist.<wbr= >github.com/abathur/b3d3d258853<wbr>03eb216e0ffa2d2604034</a></div><div sty= le=3D"font-size:12.800000190734863px"><br></div><div style=3D"font-size:12.= 800000190734863px">In this example, you can see that the string going into = the database contains three different formats: an HTML header, plaintext ma= rkup, and Doxygen commands.=C2=A0</div><div style=3D"font-size:12.800000190= 734863px"><br></div><div style=3D"font-size:12.800000190734863px">Context: = `generateSqlite3ForPage` is one of the parts of sqlite3gen that I'm ref= ining as I work on a broader project that generates Doxygen-ready source fi= les and markdown pages from a large Sphinx/RST corpus.=C2=A0</div><div styl= e=3D"font-size:12.800000190734863px"><br></div><div style=3D"font-size:12.8= 00000190734863px">Cheers,</div><div style=3D"font-size:12.800000190734863px= ">Travis</div></div></div><div class=3D"gmail_extra"><br><div class=3D"gmai= l_quote"><div class=3D"quoted-text">On Sun, Jul 9, 2017 at 11:48 PM, Adrian= M Negreanu <span dir=3D"ltr"><<a href=3D"mailto:[email protected]" targe= t=3D"_blank">[email protected]</a>></span> wrote:<br></div><div class=3D"= elided-text"><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;b= order-left:1px #ccc solid;padding-left:1ex"><div dir=3D"auto"><div>Hi Travi= s,</div><div dir=3D"auto"><br></div><div dir=3D"auto">The format of the des= cription is dictated by the client's needs. Or in other words, where th= at description is used.</div><div dir=3D"auto"><br></div><div dir=3D"auto">= I'm using it from python scripts which makes it easy to parse the curre= nt plain text.</div><div dir=3D"auto"><br></div><div dir=3D"auto">This brin= gs me to the question : why do you need another format, say (A), when you&#= 39;ll already have to parse the plaintext format to extract the semantic ne= eded by (A) ?</div><div dir=3D"auto"><br></div><div dir=3D"auto">One reason= for adding (A) is "it's easier for the client to use/parse",= which brings me again, to the first part : what client do you have ?</div>= <div dir=3D"auto"><br></div><div dir=3D"auto">Regards</div><div dir=3D"auto= "><br><div class=3D"gmail_extra" dir=3D"auto"><br><div class=3D"gmail_quote= "><div><div class=3D"m_-3314324299415030762h5">On Jul 10, 2017 3:21 AM, &qu= ot;Travis Everett" <<a href=3D"mailto:[email protected]" t= arget=3D"_blank">[email protected]</a>> wrote:<br type=3D"attri= bution"></div></div><blockquote class=3D"m_-3314324299415030762m_5160916996= 955980396quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;paddi= ng-left:1ex"><div><div class=3D"m_-3314324299415030762h5"><div dir=3D"ltr">= All,<div><br></div><div>I'm resuming work on refining the experimental = SQLite3 output. I've run into a pretty obvious quandary that I was blis= sfully ignorant of:</div><div><br></div><div>Before output-format-specific = conversion, it looks like detailed descriptions can include (at least) a mi= x of HTML and raw text that still contains doxygen commands (I haven't = gone fishing, but my guess is that markdown gets translated down to HTML, a= nd output translators are responsible for the rest).</div><div><br></div><d= iv>When it's being served by an SQL database, it doesn't seem like = there's an "obvious" or "expected" format for prese= ntational/semantic markup embedded in the detailed description. I was a bit= surprised to find plaintext Doxygen commands present at this stage.=C2=A0<= /div><div><br></div><div>I'm curious if anyone has thoughts on how to h= andle these. The best three paths forward seem to be:</div><div><br></div><= div>- Saving it as XML. I'm not keen on this since it significantly rai= ses the bar on using the sql output, and would require either updating all = of the descriptions in place, or parsing them into a more useful form on ea= ch use.</div><div>- Saving an opinionated plaintext translation. This would= retain simple usability and avoid the update-all-descriptions or constantl= y-reparse issues, as long as consumers can live with the format ;)</div><di= v>- Some active, user-configurable translation method (probably translate t= o XML and then call a user-defined translator script as with input filters.= *not sure how complex this would be or where to start; may be getting out = of my depth.</div><div><br></div><div>Thanks for any direction,</div><div>T= ravis</div></div> <br></div></div>------------------------------<wbr>------------------------= ------<wbr>------------------<br> Check out the vibrant tech community on one of the world's most<br> engaging tech sites, Slashdot.org! <a href=3D"http://sdm.link/slashdot" rel= =3D"noreferrer" target=3D"_blank">http://sdm.link/slashdot</a><br>_________= _____________________<wbr>_________________<br> Doxygen-develop mailing list<br> <a href=3D"mailto:[email protected]" target=3D"_blank">= [email protected]<wbr>rge.net</a><br> <a href=3D"https://lists.sourceforge.net/lists/listinfo/doxygen-develop" re= l=3D"noreferrer" target=3D"_blank">https://lists.sourceforge.net/<wbr>lists= /listinfo/doxygen-develop</a><br> <br></blockquote></div><br></div></div></div> </blockquote></div></div><br></div> <br>------------------------------<wbr>------------------------------<wbr>-= -----------------<br> Check out the vibrant tech community on one of the world's most<br> engaging tech sites, Slashdot.org! <a href=3D"http://sdm.link/slashdot" rel= =3D"noreferrer" target=3D"_blank">http://sdm.link/slashdot</a><br>_________= _____________________<wbr>_________________<br> Doxygen-develop mailing list<br> <a href=3D"mailto:[email protected]">Doxygen-develop@li= sts.<wbr>sourceforge.net</a><br> <a href=3D"https://lists.sourceforge.net/lists/listinfo/doxygen-develop" re= l=3D"noreferrer" target=3D"_blank">https://lists.sourceforge.net/<wbr>lists= /listinfo/doxygen-develop</a><br> <br></blockquote></div><br></div> --001a113cf13ee8550a0553f8bead-- --===============1663581463318645070== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot --===============1663581463318645070== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Doxygen-develop mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/doxygen-develop --===============1663581463318645070==--