search

dotnet / fsharp

The F# compiler, F# core library, F# language service, and F# tooling integration for Visual Studio
https://dotnet.microsoft.com/languages/fsharp
MIT License
3.89k stars 784 forks source link

Please document EmbeddedText #6890

Open 0x53A opened 5 years ago

0x53A commented 5 years ago

I just noticed that I can also use the FSComp.txt mechanism in my own projects without having to pull in any additional tools by using <EmbeddedText> Include="..." GenerateSource="true" />, but couldn't find any reference to this in msdn.

Is this supposed to be used by users, or just for internal consumption?

(I can't find any other OSS consumers: https://github.com/search?l=&p=1&q=EmbeddedText+filename%3A%2A.fsproj&type=Code)

It generates the resx file in the /obj/ directory. How is the localization workflow supposed to work? In this repo you seem to use these weird xliff files, how would I do it with multiple plain resx? Can I control where the resx is written to? Then I'd just check it in, we already have tools to translate and sync resx.

(I checked https://github.com/dotnet/fsharp/blob/ccb913d3a05863e5b1861d64994ffb97ed498855/src/fsharp/FSharp.Build/FSharpEmbedResourceText.fs and there doesn't seem to be a way to control the output path.)

Any updates on the readme for https://github.com/fsprojects/zzarchive-FsSrGen would be appreciated, it just shows archived, but not why, and what users are supposed to use.

0x53A commented 5 years ago

I was really excited when I found <EmbeddedText ... />, but looking at it a bit more and at the history, seems to be internal only.

I'm gonna copy-paste https://raw.githubusercontent.com/dotnet/fsharp/ccb913d3a05863e5b1861d64994ffb97ed498855/src/fsharp/FSharp.Build/FSharpEmbedResourceText.fs and try to adapt it a bit to my needs.

KevinRansom commented 5 years ago

@0x53A, you can use it, it's a public usable API.

0x53A commented 5 years ago

I did use it, and it worked, but it lacks a bit of polish. That, combined with the nonexistent documentation made me think that it was probably mostly/only created for internal consumption, even if technically usable from outside.

My issues were:

Would you be willing to change it / accept PRs to extend this feature?

KevinRansom commented 5 years ago

@0x53A you are welcome to improve it. And absolutely, PR's are welcome. One big caveat … we have no control over the LKG used to build this repo, and so, whatever changes you make, we can't rely on them in this build until the LKG is upgraded which is beyond our control now :-(

0x53A commented 5 years ago

Thanks!

I'll have to fork it in the short term anyway because I'd guess that even sdk 3.0 would be a difficult target, and I want it now.

I think my preferred workflow would be to generate the two artefacts (.resx / .fs) next to the .txt and commit them.

This would enable us to reuse all our existing resx tooling.

Does that make sense?

Proposed changes:

Add the following attributes to <EmbeddedText />:

<EmbeddedText Include="Loc.txt" SourceVisibility="Public" SourceOutputFilePath="Loc.fs" ResourceOutputFilePath="Loc.resx" />
dsyme commented 2 years ago

I did use it, and it worked, but it lacks a bit of polish. That, combined with the nonexistent documentation made me think that it was probably mostly/only created for internal consumption, even if technically usable from outside.

This is mostly an internal tool, but as @KevinRansom says it's externally usable

It should really be documented via a tooling RFC at https://github.com/fsharp/fslang-design/tree/main/tooling